DEBUGGER(2)DEBUGGER(2)
NAME
cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff,
fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos,
leieeesftos, leieeedftos, ieeesftos, ieeedftos – machine-independent debugger functions
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <bio.h>
#include <mach.h>
int cisctrace(Map *map, uvlong pc, uvlong sp, uvlong link,
Tracer trace)
int risctrace(Map *map, uvlong pc, uvlong sp, uvlong link,
Tracer trace)
uvlong ciscframe(Map *map, uvlong addr, uvlong pc, uvlong sp,
uvlong link)
uvlong riscframe(Map *map, uvlong addr, uvlong pc, uvlong sp,
uvlong link)
int localaddr(Map *map, char *fn, char *var, uvlong *ret,
Rgetter rget)
int symoff(char *buf, int n, uvlong addr, int type)
int fpformat(Map *map, Reglist *rp, char *buf, int n, int code)
int beieee80ftos(char *buf, int n, void *fp)
int beieeesftos(char *buf, int n, void *fp)
int beieeedftos(char *buf, int n, void *fp)
int leieee80ftos(char *buf, int n, void *fp)
int leieeesftos(char *buf, int n, void *fp)
int leieeedftos(char *buf, int n, void *fp)
int ieeesftos(char *buf, int n, ulong f)
int ieeedftos(char *buf, int n, ulong high, ulong low)
extern Machdata *machdata;
DESCRIPTION
These functions provide machine-independent implementations
of common debugger functions.
Many of the functions assume that global variables
mach
and
machdata
point to the
Mach
and
Machdata
data structures describing the target architecture.
The former contains machine parameters and a description of
the register set; it is usually
set by invoking
crackhdr
(see
mach(2))
to interpret the header of an executable.
The
Machdata
structure
is primarily a jump table specifying
functions appropriate for processing an
executable image for a given architecture.
Each application is responsible for setting
machdata
to the address of the
Machdata
structure for the target architecture.
Many of the functions described here are not
called directly; instead, they are invoked
indirectly through the
Machdata
jump table.
These functions must retrieve data and register contents
from an executing image. The
Map
(see
mach(2))
data structure
supports the consistent retrieval of data, but
no uniform access mechanism exists for registers.
The application passes the address of a register
retrieval function as an argument to those functions
requiring register values.
This function, called an
Rgetter,
is of the form
ulong rget(Map *map, char *name);
It returns the contents of a register when given
the address of a
Map
associated with an executing image and the name of the register.
Cisctrace
and
risctrace
unwind the stack for up to 40 levels or until the frame for
main
is found. They return the
count of the number of levels unwound. These functions
process stacks conforming to the generic compiler model for
RISC
and
CISC
architectures, respectively.
Map
is the address of a
Map
data structure associated with the image
of an executing process.
Sp,
pc
and
link
are starting values for the stack pointer, program counter, and
link register from which the unwinding is to take place. Normally, they are
the current contents of the appropriate
registers but they can be any values defining a legitimate
process context, for example, an alternate stack in a
multi-threaded process.
Trace
is the address of an application-supplied function to be called
on each iteration as the frame unwinds. The prototype of this
function is:
void tracer(Map *map, ulong pc, ulong fp, Symbol *s);
where
Map
is the
Map
pointer passed to
cisctrace
or
risctrace
and
pc
and
fp
are the program counter and frame pointer.
S
is the address of a
Symbol
structure, as defined in
symbol(2),
containing the symbol table information for the
function owning the frame (i.e., the function that
caused the frame to be instantiated).
Ciscframe
and
riscframe
calculate the frame pointer associated with
a function. They are suitable for
programs conforming to the
CISC
and
RISC
stack models.
Map
is the address of a
Map
associated with the memory image of an executing
process.
Addr
is the entry point of the desired function.
Pc,
sp
and
link
are the program counter, stack pointer and link register of
an execution context. As with the stack trace
functions, these can be the current values of the
registers or any legitimate execution context.
The value of the frame pointer is returned. A return
value of zero indicates an error.
Localaddr
fills the location
pointed to by
ret
with the address of a local variable.
Map
is the address of a
Map
associated with an executing memory image.
Fn
and
var
are pointers to the names of the function and variable of interest.
Rget
is the address of a register retrieval function.
If both
fn
and
var
are non-zero, the frame for function
fn
is calculated and the address of the automatic or
argument named
var
in that frame is returned.
If
var
is zero, the address of the
frame for function
fn
is returned.
In all cases, the frame for the function named
fn
must be instantiated somewhere on the current stack.
If there are multiple frames for the function (that is, if
it is recursive), the most recent frame is used.
The search starts from the context defined by the
current value of the program counter and stack pointer.
If a valid address is found,
localaddr
returns 1. A negative return indicates an error in
resolving the address.
Symoff
converts a virtual address to a symbolic reference. The
string containing that reference is of
the form ‘name+offset’, where ‘name’ is the name of the
nearest symbol with an address less than
or equal to the target address and ‘offset’ is the hexadecimal offset
beyond that symbol. If ‘offset’ is zero, only the name of
the symbol is printed. If no symbol is found within 4,096
bytes of the address, the address is formatted as a hexadecimal
address.
Buf
is the address of a buffer of
n
characters to receive the formatted string.
Addr
is the address to be converted.
Type
is the type code of the search space:
CTEXT,
CDATA,
or
CANY.
Symoff
returns the length of the formatted string contained in
buf.
Fpformat
converts the contents of a floating point register to a
string.
Map
is the address of a
Map
associated with an executing process.
Rp
is the address of a
Reglist
data structure describing the desired register.
Buf
is the address of a buffer of
n
characters to hold the resulting string.
Code
must be either
F
or
f,
selecting double
or single precision, respectively. If
code
is
F,
the contents of the specified register and
the following register
are interpreted as a double precision floating point
number; this
is only meaningful for architectures that implement
double precision floats by combining adjacent
single precision registers.
For
code
f,
the specified register is formatted
as a single precision float.
Fpformat
returns 1 if the number is successfully converted or –1
in the case of an error.
Beieee80ftos,
beieeesftos
and
beieeedftos
convert big-endian 80-bit extended, 32-bit single precision,
and 64-bit double precision floating point values to
a string.
Leieee80ftos,
leieeesftos,
and
leieeedftos
are the little-endian counterparts.
Buf
is the address of a buffer of
n
characters to receive the formatted string.
Fp
is the address of the floating point value to be
converted. These functions return the length of
the resulting string.
Ieeesftos
converts the 32-bit single precision floating point value
f,
to a string in
buf,
a buffer of
n
bytes. It returns the length of the resulting string.
Ieeedftos
converts a 64-bit double precision floating point value
to a character string.
Buf
is the address of a buffer of
n
characters to hold the resulting string.
High
and
low
contain the most and least significant 32 bits of
the floating point value, respectively.
Ieeedftos
returns the number of characters in the resulting string.
SOURCE
/sys/src/libmach
SEE ALSO
mach(2),
symbol(2),
errstr(2)
DIAGNOSTICS
Set
errstr.