plan9fox/sys/man/2/debugger

.TH DEBUGGER 2
.SH NAME
cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff,
fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos,
leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.nf
.B
int cisctrace(Map *map, ulong pc, ulong sp, ulong link,
.B
              Tracer trace)
.PP
.nf
.B
int risctrace(Map *map, ulong pc, ulong sp, ulong link,
.B
              Tracer trace)
.PP
.nf
.B
ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp,
.B
                ulong link)
.PP
.nf
.B
ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp,
.B
                ulong link)
.PP
.nf
.B
int localaddr(Map *map, char *fn, char *var, long *ret,
.B
              Rgetter rget)
.PP
.B
int symoff(char *buf, int n, long addr, int type)
.PP
.B
int fpformat(Map *map, Reglist *rp, char *buf, int n, int code)
.PP
.B
int beieee80ftos(char *buf, int n, void *fp)
.PP
.B
int beieeesftos(char *buf, int n, void *fp)
.PP
.B
int beieeedftos(char *buf, int n, void *fp)
.PP
.B
int leieee80ftos(char *buf, int n, void *fp)
.PP
.B
int leieeesftos(char *buf, int n, void *fp)
.PP
.B
int leieeedftos(char *buf, int n, void *fp)
.PP
.B
int ieeesftos(char *buf, int n, ulong f)
.PP
.B
int ieeedftos(char *buf, int n, ulong high, ulong low)
.PP
.B
extern Machdata *machdata;
.SH DESCRIPTION
These functions provide machine-independent implementations
of common debugger functions.
Many of the functions assume that global variables
.I mach
and
.I machdata
point to the
.I Mach
and
.I 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
.I crackhdr
(see
.IR mach (2))
to interpret the header of an executable.
The
.I 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
.I machdata
to the address of the
.I Machdata
structure for the target architecture. 
Many of the functions described here are not
called directly; instead, they are invoked
indirectly through the
.I Machdata
jump table.
.PP
These functions must retrieve data and register contents
from an executing image.  The
.I Map
(see
.IR 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
.IR Rgetter ,
is of the form
.PP
.RS
.B "ulong rget(Map *map, char *name);
.RE
.PP
It returns the contents of a register when given
the address of a
.I Map
associated with an executing image and the name of the register.
.PP
.I Cisctrace
and
.I risctrace
unwind the stack for up to 40 levels or until the frame for
.I main
is found.  They return the
count of the number of levels unwound.  These functions
process stacks conforming to the generic compiler model for
.SM RISC
and
.SM CISC
architectures, respectively.
.I Map
is the address of a
.I Map
data structure associated with the image
of an executing process.
.IR Sp ,
.I pc
and
.I 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.
.I 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:
.PP
.RS
.B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s);
.RE
.PP
where
.I Map
is the
.I Map
pointer passed to
.I cisctrace
or
.I risctrace
and
.I pc
and
.I fp
are the program counter and frame pointer.
.I S
is the address of a 
.I Symbol
structure, as defined in
.IR symbol (2),
containing the symbol table information for the
function owning the frame (i.e., the function that
caused the frame to be instantiated).
.PP
.I Ciscframe
and
.I riscframe
calculate the frame pointer associated with
a function.  They are suitable for
programs conforming to the
.SM CISC
and
.SM RISC
stack models.
.I Map
is the address of a
.I Map
associated with the memory image of an executing
process.
.I Addr
is the entry point of the desired function.
.IR Pc ,
.I sp
and
.I 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.
.PP
.I Localaddr
fills the location
pointed to by
.I ret
with the address of a local variable.
.I Map
is the address of a
.I Map
associated with an executing memory image.
.I Fn
and
.I var
are pointers to the names of the function and variable of interest.
.I Rget
is the address of a register retrieval function.
If both
.I fn
and
.I var
are non-zero, the frame for function
.I fn
is calculated and the address of the automatic or
argument named
.I var
in that frame is returned.
If
.I var
is zero, the address of the
frame for function
.I fn
is returned.
In all cases, the frame for the function named
.I 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,
.I localaddr
returns 1.  A negative return indicates an error in
resolving the address.
.PP
.I 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.
.I Buf
is the address of a buffer of
.I n
characters to receive the formatted string.
.I Addr
is the address to be converted.
.I Type
is the type code of the search space:
.BR CTEXT ,
.BR CDATA ,
or
.BR CANY .
.I Symoff
returns the length of the formatted string contained in
.IR buf .
.PP
.I Fpformat
converts the contents of a floating point register to a
string.
.I Map
is the address of a
.I Map
associated with an executing process.
.I Rp
is the address of a
.I Reglist
data structure describing the desired register.
.I Buf
is the address of a buffer of
.I n
characters to hold the resulting string.
.I Code
must be either
.B F
or
.BR f,
selecting double
or single precision, respectively.  If
.I code
is
.BR 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
.I code
.BR f ,
the specified register is formatted
as a single precision float.
.I Fpformat
returns 1 if the number is successfully converted or \-1
in the case of an error.
.PP
.IR Beieee80ftos ,
.I beieeesftos
and
.I beieeedftos
convert big-endian 80-bit extended, 32-bit single precision,
and 64-bit double precision floating point values to
a string.
.IR Leieee80ftos ,
.IR leieeesftos ,
and
.I leieeedftos
are the little-endian counterparts.
.I Buf
is the address of a buffer of
.I n
characters to receive the formatted string.
.I Fp
is the address of the floating point value to be
converted.  These functions return the length of
the resulting string.
.PP
.I Ieeesftos
converts the 32-bit single precision floating point value
.IR f ,
to a string in
.IR buf ,
a buffer of
.I n
bytes.  It returns the length of the resulting string.
.PP
.I Ieeedftos
converts a 64-bit double precision floating point value
to a character string.
.I Buf
is the address of a buffer of
.I n
characters to hold the resulting string.
.I High
and
.I low
contain the most and least significant 32 bits of
the floating point value, respectively.
.I Ieeedftos
returns the number of characters in the resulting string.
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (2),
.IR symbol (2),
.IR errstr (2)
.SH DIAGNOSTICS
Set
.IR errstr .