sys/man/2/debugger

   1 .TH DEBUGGER 2
   2 .SH NAME
   3 cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff,
   4 fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos,
   5 leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions
   6 .SH SYNOPSIS
   7 .B #include <u.h>
   8 .br
   9 .B #include <libc.h>
  10 .br
  11 .B #include <bio.h>
  12 .br
  13 .B #include <mach.h>
  14 .PP
  15 .ta \w'\fLmachines 'u
  16 .nf
  17 .B
  18 int cisctrace(Map *map, uvlong pc, uvlong sp, uvlong link,
  19 .B
  20               Tracer trace)
  21 .PP
  22 .nf
  23 .B
  24 int risctrace(Map *map, uvlong pc, uvlong sp, uvlong link,
  25 .B
  26               Tracer trace)
  27 .PP
  28 .nf
  29 .B
  30 uvlong ciscframe(Map *map, uvlong addr, uvlong pc, uvlong sp,
  31 .B
  32                 uvlong link)
  33 .PP
  34 .nf
  35 .B
  36 uvlong riscframe(Map *map, uvlong addr, uvlong pc, uvlong sp,
  37 .B
  38                 uvlong link)
  39 .PP
  40 .nf
  41 .B
  42 int localaddr(Map *map, char *fn, char *var, uvlong *ret,
  43 .B
  44               Rgetter rget)
  45 .PP
  46 .B
  47 int symoff(char *buf, int n, uvlong addr, int type)
  48 .PP
  49 .B
  50 int fpformat(Map *map, Reglist *rp, char *buf, int n, int code)
  51 .PP
  52 .B
  53 int beieee80ftos(char *buf, int n, void *fp)
  54 .PP
  55 .B
  56 int beieeesftos(char *buf, int n, void *fp)
  57 .PP
  58 .B
  59 int beieeedftos(char *buf, int n, void *fp)
  60 .PP
  61 .B
  62 int leieee80ftos(char *buf, int n, void *fp)
  63 .PP
  64 .B
  65 int leieeesftos(char *buf, int n, void *fp)
  66 .PP
  67 .B
  68 int leieeedftos(char *buf, int n, void *fp)
  69 .PP
  70 .B
  71 int ieeesftos(char *buf, int n, ulong f)
  72 .PP
  73 .B
  74 int ieeedftos(char *buf, int n, ulong high, ulong low)
  75 .PP
  76 .B
  77 extern Machdata *machdata;
  78 .SH DESCRIPTION
  79 These functions provide machine-independent implementations
  80 of common debugger functions.
  81 Many of the functions assume that global variables
  82 .I mach
  83 and
  84 .I machdata
  85 point to the
  86 .I Mach
  87 and
  88 .I Machdata
  89 data structures describing the target architecture.
  90 The former contains machine parameters and a description of
  91 the register set; it is usually
  92 set by invoking
  93 .I crackhdr
  94 (see
  95 .IR mach (2))
  96 to interpret the header of an executable.
  97 The
  98 .I Machdata
  99 structure
 100 is primarily a jump table specifying
 101 functions appropriate for processing an
 102 executable image for a given architecture.
 103 Each application is responsible for setting
 104 .I machdata
 105 to the address of the
 106 .I Machdata
 107 structure for the target architecture.
 108 Many of the functions described here are not
 109 called directly; instead, they are invoked
 110 indirectly through the
 111 .I Machdata
 112 jump table.
 113 .PP
 114 These functions must retrieve data and register contents
 115 from an executing image.  The
 116 .I Map
 117 (see
 118 .IR mach (2))
 119 data structure
 120 supports the consistent retrieval of data, but
 121 no uniform access mechanism exists for registers.
 122 The application passes the address of a register
 123 retrieval function as an argument to those functions
 124 requiring register values.
 125 This function, called an
 126 .IR Rgetter ,
 127 is of the form
 128 .PP
 129 .RS
 130 .B "ulong rget(Map *map, char *name);
 131 .RE
 132 .PP
 133 It returns the contents of a register when given
 134 the address of a
 135 .I Map
 136 associated with an executing image and the name of the register.
 137 .PP
 138 .I Cisctrace
 139 and
 140 .I risctrace
 141 unwind the stack for up to 40 levels or until the frame for
 142 .I main
 143 is found.  They return the
 144 count of the number of levels unwound.  These functions
 145 process stacks conforming to the generic compiler model for
 146 .SM RISC
 147 and
 148 .SM CISC
 149 architectures, respectively.
 150 .I Map
 151 is the address of a
 152 .I Map
 153 data structure associated with the image
 154 of an executing process.
 155 .IR Sp ,
 156 .I pc
 157 and
 158 .I link
 159 are starting values for the stack pointer, program counter, and
 160 link register from which the unwinding is to take place.  Normally, they are
 161 the current contents of the appropriate
 162 registers but they can be any values defining a legitimate
 163 process context, for example, an alternate stack in a
 164 multi-threaded process.
 165 .I Trace
 166 is the address of an application-supplied function to be called
 167 on each iteration as the frame unwinds.  The prototype of this
 168 function is:
 169 .PP
 170 .RS
 171 .B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s);
 172 .RE
 173 .PP
 174 where
 175 .I Map
 176 is the
 177 .I Map
 178 pointer passed to
 179 .I cisctrace
 180 or
 181 .I risctrace
 182 and
 183 .I pc
 184 and
 185 .I fp
 186 are the program counter and frame pointer.
 187 .I S
 188 is the address of a
 189 .I Symbol
 190 structure, as defined in
 191 .IR symbol (2),
 192 containing the symbol table information for the
 193 function owning the frame (i.e., the function that
 194 caused the frame to be instantiated).
 195 .PP
 196 .I Ciscframe
 197 and
 198 .I riscframe
 199 calculate the frame pointer associated with
 200 a function.  They are suitable for
 201 programs conforming to the
 202 .SM CISC
 203 and
 204 .SM RISC
 205 stack models.
 206 .I Map
 207 is the address of a
 208 .I Map
 209 associated with the memory image of an executing
 210 process.
 211 .I Addr
 212 is the entry point of the desired function.
 213 .IR Pc ,
 214 .I sp
 215 and
 216 .I link
 217 are the program counter, stack pointer and link register of
 218 an execution context.  As with the stack trace
 219 functions, these can be the current values of the
 220 registers or any legitimate execution context.
 221 The value of the frame pointer is returned.  A return
 222 value of zero indicates an error.
 223 .PP
 224 .I Localaddr
 225 fills the location
 226 pointed to by
 227 .I ret
 228 with the address of a local variable.
 229 .I Map
 230 is the address of a
 231 .I Map
 232 associated with an executing memory image.
 233 .I Fn
 234 and
 235 .I var
 236 are pointers to the names of the function and variable of interest.
 237 .I Rget
 238 is the address of a register retrieval function.
 239 If both
 240 .I fn
 241 and
 242 .I var
 243 are non-zero, the frame for function
 244 .I fn
 245 is calculated and the address of the automatic or
 246 argument named
 247 .I var
 248 in that frame is returned.
 249 If
 250 .I var
 251 is zero, the address of the
 252 frame for function
 253 .I fn
 254 is returned.
 255 In all cases, the frame for the function named
 256 .I fn
 257 must be instantiated somewhere on the current stack.
 258 If there are multiple frames for the function (that is, if
 259 it is recursive), the most recent frame is used.
 260 The search starts from the context defined by the
 261 current value of the program counter and stack pointer.
 262 If a valid address is found,
 263 .I localaddr
 264 returns 1.  A negative return indicates an error in
 265 resolving the address.
 266 .PP
 267 .I Symoff
 268 converts a virtual address to a symbolic reference.  The
 269 string containing that reference is of
 270 the form `name+offset', where `name' is the name of the
 271 nearest symbol with an address less than
 272 or equal to the target address and `offset' is the hexadecimal offset
 273 beyond that symbol.  If `offset' is zero, only the name of
 274 the symbol is printed.  If no symbol is found within 4,096
 275 bytes of the address, the address is formatted as a hexadecimal
 276 address.
 277 .I Buf
 278 is the address of a buffer of
 279 .I n
 280 characters to receive the formatted string.
 281 .I Addr
 282 is the address to be converted.
 283 .I Type
 284 is the type code of the search space:
 285 .BR CTEXT ,
 286 .BR CDATA ,
 287 or
 288 .BR CANY .
 289 .I Symoff
 290 returns the length of the formatted string contained in
 291 .IR buf .
 292 .PP
 293 .I Fpformat
 294 converts the contents of a floating point register to a
 295 string.
 296 .I Map
 297 is the address of a
 298 .I Map
 299 associated with an executing process.
 300 .I Rp
 301 is the address of a
 302 .I Reglist
 303 data structure describing the desired register.
 304 .I Buf
 305 is the address of a buffer of
 306 .I n
 307 characters to hold the resulting string.
 308 .I Code
 309 must be either
 310 .B F
 311 or
 312 .BR f,
 313 selecting double
 314 or single precision, respectively.  If
 315 .I code
 316 is
 317 .BR F ,
 318 the contents of the specified register and
 319 the following register
 320 are interpreted as a double precision floating point
 321 number; this
 322 is only meaningful for architectures that implement
 323 double precision floats by combining adjacent
 324 single precision registers.
 325 For
 326 .I code
 327 .BR f ,
 328 the specified register is formatted
 329 as a single precision float.
 330 .I Fpformat
 331 returns 1 if the number is successfully converted or \-1
 332 in the case of an error.
 333 .PP
 334 .IR Beieee80ftos ,
 335 .I beieeesftos
 336 and
 337 .I beieeedftos
 338 convert big-endian 80-bit extended, 32-bit single precision,
 339 and 64-bit double precision floating point values to
 340 a string.
 341 .IR Leieee80ftos ,
 342 .IR leieeesftos ,
 343 and
 344 .I leieeedftos
 345 are the little-endian counterparts.
 346 .I Buf
 347 is the address of a buffer of
 348 .I n
 349 characters to receive the formatted string.
 350 .I Fp
 351 is the address of the floating point value to be
 352 converted.  These functions return the length of
 353 the resulting string.
 354 .PP
 355 .I Ieeesftos
 356 converts the 32-bit single precision floating point value
 357 .IR f ,
 358 to a string in
 359 .IR buf ,
 360 a buffer of
 361 .I n
 362 bytes.  It returns the length of the resulting string.
 363 .PP
 364 .I Ieeedftos
 365 converts a 64-bit double precision floating point value
 366 to a character string.
 367 .I Buf
 368 is the address of a buffer of
 369 .I n
 370 characters to hold the resulting string.
 371 .I High
 372 and
 373 .I low
 374 contain the most and least significant 32 bits of
 375 the floating point value, respectively.
 376 .I Ieeedftos
 377 returns the number of characters in the resulting string.
 378 .SH SOURCE
 379 .B /sys/src/libmach
 380 .SH "SEE ALSO"
 381 .IR mach (2),
 382 .IR symbol (2),
 383 .IR errstr (2)
 384 .SH DIAGNOSTICS
 385 Set
 386 .IR errstr .