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, ulong pc, ulong sp, ulong link,
                        Tracer trace)

          int risctrace(Map *map, ulong pc, ulong sp, ulong link,
                        Tracer trace)

          ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp,
                          ulong link)

          ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp,
                          ulong link)

          int localaddr(Map *map, char *fn, char *var, long *ret,
                        Rgetter rget)

          int symoff(char *buf, int n, long 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

     DEBUGGER(2)                                           DEBUGGER(2)

          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 architec-
          ture.  The former contains machine parameters and a descrip-
          tion of the register set; it is usually set by invoking
          crackhdr (see mach(2)) to interpret the header of an exe-
          cutable.  The Machdata structure is primarily a jump table
          specifying functions appropriate for processing an exe-
          cutable 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 struc-
          ture supports the consistent retrieval of data, but no uni-
          form 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

     DEBUGGER(2)                                           DEBUGGER(2)

          caused the frame to be instantiated).

          Ciscframe and riscframe calculate the frame pointer associ-
          ated with a function.  They are suitable for programs con-
          forming to the CISC and RISC stack models.  Map is the
          address of a Map associated with the memory image of an exe-
          cuting 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 inter-
          est.  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 instanti-
          ated 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 con-
          text 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 resolv-
          ing 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 sym-
          bol 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

     DEBUGGER(2)                                           DEBUGGER(2)

          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 preci-
          sion registers.  For code f, the specified register is for-
          matted 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 counter-
          parts.  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 float-
          ing 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.