1
0

debugger 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386
  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, ulong pc, ulong sp, ulong link,
  19. .B
  20. Tracer trace)
  21. .PP
  22. .nf
  23. .B
  24. int risctrace(Map *map, ulong pc, ulong sp, ulong link,
  25. .B
  26. Tracer trace)
  27. .PP
  28. .nf
  29. .B
  30. ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp,
  31. .B
  32. ulong link)
  33. .PP
  34. .nf
  35. .B
  36. ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp,
  37. .B
  38. ulong link)
  39. .PP
  40. .nf
  41. .B
  42. int localaddr(Map *map, char *fn, char *var, long *ret,
  43. .B
  44. Rgetter rget)
  45. .PP
  46. .B
  47. int symoff(char *buf, int n, long 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 .