term% cat index.txt DEBUGGER(2) System Calls Manual DEBUGGER(2)
NAME
cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff, fpfor‐
mat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos, leieeesftos,
leieeedftos, ieeesftos, ieeedftos - machine-independent debugger func‐
tions
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 de‐
scribing the target architecture. The former contains machine parame‐
ters and a description of the register set; it is usually set by invok‐
ing 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 architec‐
ture. Each application is responsible for setting machdata to the ad‐
dress 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 exe‐
cuting image. The Map (see mach(2)) data structure supports the con‐
sistent 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 un‐
winding is to take place. Normally, they are the current contents of
the appropriate registers but they can be any values defining a legiti‐
mate 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 pro‐
totype 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 ta‐
ble 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 execut‐
ing 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 indi‐
cates 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 dou‐
ble 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 ar‐
chitectures that implement double precision floats by combining adja‐
cent single precision registers. For code f, the specified register is
formatted as a single precision float. Fpformat returns 1 if the num‐
ber is successfully converted or -1 in the case of an error.
Beieee80ftos, beieeesftos and beieeedftos convert big-endian 80-bit ex‐
tended, 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.
DEBUGGER(2)