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
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
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
ulong rget(Map *map, char *name);|
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
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
void tracer(Map *map, ulong pc, ulong fp, Symbol *s);|