acid.ms 64 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550
  1. .HTML "Acid Manual
  2. .am DS
  3. .ft I
  4. ..
  5. .ta 1i 2.3i 4.5i (optional to set tabs)
  6. .TL
  7. Acid Manual
  8. .AU
  9. Phil Winterbottom
  10. philw@plan9.bell-labs.com
  11. .SH
  12. Introduction
  13. .PP
  14. Acid is a general purpose, source level symbolic debugger.
  15. The debugger is built around a simple command language.
  16. The command language, distinct from the language of the program being debugged,
  17. provides a flexible user interface that allows the debugger
  18. interface to be customized for a specific application or architecture.
  19. Moreover, it provides an opportunity to write test and
  20. verification code independently of a program's source code.
  21. Acid is able to debug multiple
  22. processes provided they share a common set of symbols, such as the processes in
  23. a threaded program.
  24. .PP
  25. Like other language-based solutions, Acid presents a poor user interface but
  26. provides a powerful debugging tool.
  27. Application of Acid to hard problems is best approached by writing functions off-line
  28. (perhaps loading them with the
  29. .CW include
  30. function or using the support provided by
  31. .I acme (1)),
  32. rather than by trying to type intricate Acid operations
  33. at the interactive prompt.
  34. .PP
  35. Acid allows the execution of a program to be controlled by operating on its
  36. state while it is stopped and by monitoring and controlling its execution
  37. when it is running. Each program action that causes a change
  38. of execution state is reflected by the execution
  39. of an Acid function, which may be user defined.
  40. A library of default functions provides the functionality of a normal debugger.
  41. .PP
  42. A Plan 9 process is controlled by writing messages to a control file in the
  43. .I proc (3)
  44. file system. Each control message has a corresponding Acid function, which
  45. sends the message to the process. These functions take a process id
  46. .I pid ) (
  47. as an
  48. argument. The memory and text file of the program may be manipulated using
  49. the indirection operators. The symbol table, including source cross reference,
  50. is available to an Acid program. The combination allows complex operations
  51. to be performed both in terms of control flow and data manipulation.
  52. .SH
  53. Input format and \f(CWwhatis\fP
  54. .PP
  55. Comments start with
  56. .CW //
  57. and continue to the end of the line.
  58. Input is a series of statements and expressions separated by semicolons.
  59. At the top level of the interpreter, the builtin function
  60. .CW print
  61. is called automatically to display the result of all expressions except function calls.
  62. A unary
  63. .CW +
  64. may be used as a shorthand to force the result of a function call to be printed.
  65. .PP
  66. Also at the top level, newlines are treated as semicolons
  67. by the parser, so semicolons are unnecessary when evaluating expressions.
  68. .PP
  69. When Acid starts, it loads the default program modules,
  70. enters interactive mode, and prints a prompt. In this state Acid accepts
  71. either function definitions or statements to be evaluated.
  72. In this interactive mode
  73. statements are evaluated immediately, while function definitions are
  74. stored for later invocation.
  75. .PP
  76. The
  77. .CW whatis
  78. operator can be used to report the state of identifiers known to the interpreter.
  79. With no argument,
  80. .CW whatis
  81. reports the name of all defined Acid functions; when supplied with an identifier
  82. as an argument it reports any variable, function, or type definition
  83. associated with the identifier.
  84. Because of the way the interpreter handles semicolons,
  85. the result of a
  86. .CW whatis
  87. statement can be returned directly to Acid without adding semicolons.
  88. A syntax error or interrupt returns Acid to the normal evaluation
  89. mode; any partially evaluated definitions are lost.
  90. .SH
  91. Using the Library Functions
  92. .PP
  93. After loading the program binary, Acid loads the portable and architecture-specific
  94. library functions that form the standard debugging environment.
  95. These files are Acid source code and are human-readable.
  96. The following example uses the standard debugging library to show how
  97. language and program interact:
  98. .P1
  99. % acid /bin/ls
  100. /bin/ls:mips plan 9 executable
  101. /sys/lib/acid/port
  102. /sys/lib/acid/mips
  103. acid: new()
  104. 75721: system call _main ADD $-0x14,R29
  105. 75721: breakpoint main+0x4 MOVW R31,0x0(R29)
  106. acid: bpset(ls)
  107. acid: cont()
  108. 75721: breakpoint ls ADD $-0x16c8,R29
  109. acid: stk()
  110. At pc:0x0000141c:ls /sys/src/cmd/ls.c:87
  111. ls(s=0x0000004d,multi=0x00000000) /sys/src/cmd/ls.c:87
  112. called from main+0xf4 /sys/src/cmd/ls.c:79
  113. main(argc=0x00000000,argv=0x7ffffff0) /sys/src/cmd/ls.c:48
  114. called from _main+0x20 /sys/src/libc/mips/main9.s:10
  115. acid: PC
  116. 0xc0000f60
  117. acid: *PC
  118. 0x0000141c
  119. acid: ls
  120. 0x0000141c
  121. .P2
  122. The function
  123. .CW new()
  124. creates a new process and stops it at the first instruction.
  125. This change in state is reported by a call to the
  126. Acid function
  127. .CW stopped ,
  128. which is called by the interpreter whenever the debugged program stops.
  129. .CW Stopped
  130. prints the status line giving the pid, the reason the program stopped
  131. and the address and instruction at the current PC.
  132. The function
  133. .CW bpset
  134. makes an entry in the breakpoint table and plants a breakpoint in memory.
  135. The
  136. .CW cont
  137. function continues the process, allowing it to run until some condition
  138. causes it to stop. In this case the program hits the breakpoint placed on
  139. the function
  140. .CW ls
  141. in the C program. Once again the
  142. .CW stopped
  143. routine is called to print the status of the program. The function
  144. .CW stk
  145. prints a C stack trace of the current process. It is implemented using
  146. a builtin Acid function that returns the stack trace as a list; the code
  147. that formats the information is all written in Acid.
  148. The Acid variable
  149. .CW PC
  150. holds the address of the
  151. cell where the current value of the processor register
  152. .CW PC
  153. is stored. By indirecting through
  154. the value of
  155. .CW PC
  156. the address where the program is stopped can be found.
  157. All of the processor registers are available by the same mechanism.
  158. .SH
  159. Types
  160. .PP
  161. An Acid variable has one of four types:
  162. .I integer ,
  163. .I float ,
  164. .I list ,
  165. or
  166. .I string .
  167. The type of a variable is inferred from the type of the right-hand
  168. side of the assignment expression which last set its value.
  169. Referencing a variable that has not yet
  170. been assigned draws a "used but not set" error. Many of the operators may
  171. be applied to more than
  172. one type; for these operators the action of the operator is determined by
  173. the types of its operands. The action of each operator is defined in the
  174. .I Expressions
  175. section of this manual.
  176. .SH
  177. Variables
  178. .PP
  179. Acid has three kinds of variables: variables defined by the symbol table
  180. of the debugged program, variables that are defined and maintained
  181. by the interpreter as the debugged program changes state, and variables
  182. defined and used by Acid programs.
  183. .PP
  184. Some examples of variables maintained by the interpreter are the register
  185. pointers listed by name in the Acid list variable
  186. .CW registers ,
  187. and the symbol table listed by name and contents in the Acid variable
  188. .CW symbols .
  189. .PP
  190. The variable
  191. .CW pid
  192. is updated by the interpreter to select the most recently created process
  193. or the process selected by the
  194. .CW setproc
  195. builtin function.
  196. .SH 1
  197. Formats
  198. .PP
  199. In addition to a type, variables have formats. The format is a code
  200. letter that determines the printing style and the effect of some of the
  201. operators on that variable. The format codes are derived from the format
  202. letters used by
  203. .I db (1).
  204. By default, symbol table variables and numeric constants
  205. are assigned the format code
  206. .CW X ,
  207. which specifies 32-bit hexadecimal.
  208. Printing a variable with this code yields the output
  209. .CW 0x00123456 .
  210. The format code of a variable may be changed from the default by using the
  211. builtin function
  212. .CW fmt .
  213. This function takes two arguments, an expression and a format code. After
  214. the expression is evaluated the new format code is attached to the result
  215. and forms the return value from
  216. .CW fmt .
  217. The backslash operator is a short form of
  218. .CW fmt .
  219. The format supplied by the backslash operator must be the format character
  220. rather than an expression.
  221. If the result is assigned to a variable the new format code is maintained
  222. in the variable. For example:
  223. .P1
  224. acid: x=10
  225. acid: print(x)
  226. 0x0000000a
  227. acid: x = fmt(x, 'D')
  228. acid: print(x, fmt(x, 'X'))
  229. 10 0x0000000a
  230. acid: x
  231. 10
  232. acid: x\eo
  233. 12
  234. .P2
  235. The supported format characters are:
  236. .RS
  237. .IP \f(CWo\fP
  238. Print two-byte integer in octal.
  239. .IP \f(CWO\fP
  240. Print four-byte integer in octal.
  241. .IP \f(CWq\fP
  242. Print two-byte integer in signed octal.
  243. .IP \f(CWQ\fP
  244. Print four-byte integer in signed octal.
  245. .IP \f(CWB\fP
  246. Print four-byte integer in binary.
  247. .IP \f(CWd\fP
  248. Print two-byte integer in signed decimal.
  249. .IP \f(CWD\fP
  250. Print four-byte integer in signed decimal.
  251. .IP \f(CWV\fP
  252. Print eight-byte integer in signed decimal.
  253. .IP \f(CWZ\fP
  254. Print eight-byte integer in unsigned decimal.
  255. .IP \f(CWx\fP
  256. Print two-byte integer in hexadecimal.
  257. .IP \f(CWX\fP
  258. Print four-byte integer in hexadecimal.
  259. .IP \f(CWY\fP
  260. Print eight-byte integer in hexadecimal.
  261. .IP \f(CWu\fP
  262. Print two-byte integer in unsigned decimal.
  263. .IP \f(CWU\fP
  264. Print four-byte integer in unsigned decimal.
  265. .IP \f(CWf\fP
  266. Print single-precision floating point number.
  267. .IP \f(CWF\fP
  268. Print double-precision floating point number.
  269. .IP \f(CWg\fP
  270. Print a single precision floating point number in string format.
  271. .IP \f(CWG\fP
  272. Print a double precision floating point number in string format.
  273. .IP \f(CWb\fP
  274. Print byte in hexadecimal.
  275. .IP \f(CWc\fP
  276. Print byte as an ASCII character.
  277. .IP \f(CWC\fP
  278. Like
  279. .CW c ,
  280. with
  281. printable ASCII characters represented normally and
  282. others printed in the form \f(CW\ex\fInn\fR.
  283. .IP \f(CWs\fP
  284. Interpret the addressed bytes as UTF characters
  285. and print successive characters until a zero byte is reached.
  286. .IP \f(CWr\fP
  287. Print a two-byte integer as a rune.
  288. .IP \f(CWR\fP
  289. Print successive two-byte integers as runes
  290. until a zero rune is reached.
  291. .IP \f(CWi\fP
  292. Print as machine instructions.
  293. .IP \f(CWI\fP
  294. As
  295. .CW i
  296. above, but print the machine instructions in
  297. an alternate form if possible:
  298. .CW sunsparc
  299. and
  300. .CW mipsco
  301. reproduce the manufacturers' syntax.
  302. .IP \f(CWa\fP
  303. Print the value in symbolic form.
  304. .RE
  305. .SH
  306. Complex types
  307. .PP
  308. Acid permits the definition of the layout of memory.
  309. The usual method is to use the
  310. .CW -a
  311. flag of the compilers to produce Acid-language descriptions of data structures (see
  312. .I 2c (1))
  313. although such definitions can be typed interactively.
  314. The keywords
  315. .CW complex ,
  316. .CW adt ,
  317. .CW aggr ,
  318. and
  319. .CW union
  320. are all equivalent; the compiler uses the synonyms to document the declarations.
  321. A complex type is described as a set of members, each containing a format letter,
  322. an offset in the structure, and a name. For example, the C structure
  323. .P1
  324. struct List {
  325. int type;
  326. struct List *next;
  327. };
  328. .P2
  329. is described by the Acid statement
  330. .P1
  331. complex List {
  332. 'D' 0 type;
  333. 'X' 4 next;
  334. };
  335. .P2
  336. .SH
  337. Scope
  338. .PP
  339. Variables are global unless they are either parameters to functions
  340. or are declared as
  341. .CW local
  342. in a function body. Parameters and local variables are available only in
  343. the body of the function in which they are instantiated.
  344. Variables are dynamically bound: if a function declares a local variable
  345. with the same name as a global variable, the global variable will be hidden
  346. whenever the function is executing.
  347. For example, if a function
  348. .CW f
  349. has a local called
  350. .CW main ,
  351. any function called below
  352. .CW f
  353. will see the local version of
  354. .CW main ,
  355. not the external symbol.
  356. .SH 1
  357. Addressing
  358. .PP
  359. Since the symbol table specifies addresses,
  360. to access the value of program variables
  361. an extra level of indirection
  362. is required relative to the source code.
  363. For consistency, the registers are maintained as pointers as well; Acid variables with the names
  364. of processor registers point to cells holding the saved registers.
  365. .PP
  366. The location in a file or memory image associated with
  367. an address is calculated from a map
  368. associated with the file.
  369. Each map contains one or more quadruples (\c
  370. .I t ,
  371. .I b ,
  372. .I e ,
  373. .I f \|),
  374. defining a segment named
  375. .I t
  376. (usually
  377. .CW text ,
  378. .CW data ,
  379. .CW regs ,
  380. or
  381. .CW fpregs )
  382. mapping addresses in the range
  383. .I b
  384. through
  385. .I e
  386. to the part of the file
  387. beginning at
  388. offset
  389. .I f .
  390. The memory model of a Plan 9 process assumes
  391. that segments are disjoint. There
  392. can be more than one segment of a given type (e.g., a process
  393. may have more than one text segment) but segments
  394. may not overlap.
  395. An address
  396. .I a
  397. is translated
  398. to a file address
  399. by finding a segment
  400. for which
  401. .I b
  402. +
  403. .I a
  404. <
  405. .I e ;
  406. the location in the file
  407. is then
  408. .I address
  409. +
  410. .I f
  411. \-
  412. .I b .
  413. .PP
  414. Usually,
  415. the text and initialized data of a program
  416. are mapped by segments called
  417. .CW text
  418. and
  419. .CW data .
  420. Since a program file does not contain bss, stack, or register data,
  421. these data are
  422. not mapped by the data segment.
  423. The text segment is mapped similarly in the memory image of
  424. a normal (i.e., non-kernel) process.
  425. However, the segment called
  426. .CW *data
  427. maps memory from the beginning to the end of the program's data space.
  428. This region contains the program's static data, the bss, the
  429. heap and the stack. A segment
  430. called
  431. .CW *regs
  432. maps the registers;
  433. .CW *fpregs
  434. maps the floating point registers.
  435. .PP
  436. Sometimes it is useful to define a map with a single segment
  437. mapping the region from 0 to 0xFFFFFFFF; such a map
  438. allows the entire file to be examined
  439. without address translation. The builtin function
  440. .CW map
  441. examines and modifies Acid's map for a process.
  442. .SH 1
  443. Name Conflicts
  444. .PP
  445. Name conflicts between keywords in the Acid language, symbols in the program,
  446. and previously defined functions are resolved when the interpreter starts up.
  447. Each name is made unique by prefixing enough
  448. .CW $
  449. characters to the front of the name to make it unique. Acid reports
  450. a list of each name change at startup. The report looks like this:
  451. .P1
  452. /bin/sam: mips plan 9 executable
  453. /lib/acid/port
  454. /lib/acid/mips
  455. Symbol renames:
  456. append=$append T/0xa4e40
  457. acid:
  458. .P2
  459. The symbol
  460. .CW append
  461. is both a keyword and a text symbol in the program. The message reports
  462. that the text symbol is now named
  463. .CW $append .
  464. .SH
  465. Expressions
  466. .PP
  467. Operators have the same
  468. binding and precedence as in C.
  469. For operators of equal precedence, expressions are evaluated from left to right.
  470. .SH 1
  471. Boolean expressions
  472. .PP
  473. If an expression is evaluated for a boolean condition the test
  474. performed depends on the type of the result. If the result is of
  475. .I integer
  476. or
  477. .I floating
  478. type the result is true if the value is non-zero. If the expression is a
  479. .I list
  480. the result is true if there are any members in the list.
  481. If the expression is a
  482. .I string
  483. the result is true if there are any characters in the string.
  484. .DS
  485. primary-expression:
  486. identifier
  487. identifier \f(CW:\fP identifier
  488. constant
  489. \f(CW(\fP expression \f(CW)\fP
  490. \f(CW{\fP elist \f(CW}\fP
  491. elist:
  492. expression
  493. elist , expression
  494. .DE
  495. An identifier may be any legal Acid variable. The colon operator returns the
  496. address of parameters or local variables in the current stack of a program.
  497. For example:
  498. .P1
  499. *main:argc
  500. .P2
  501. prints the number of arguments passed into main. Local variables and parameters
  502. can only be referenced after the frame has been established. It may be necessary to
  503. step a program over the first few instructions of a breakpointed function to properly set
  504. the frame.
  505. .PP
  506. Constants follow the same lexical rules as C.
  507. A list of expressions delimited by braces forms a list constructor.
  508. A new list is produced by evaluating each expression when the constructor is executed.
  509. The empty list is formed from
  510. .CW {} .
  511. .P1
  512. acid: x = 10
  513. acid: l = { 1, x, 2\eD }
  514. acid: x = 20
  515. acid: l
  516. {0x00000001 , 0x0000000a , 2 }
  517. .P2
  518. .SH 1
  519. Lists
  520. .PP
  521. Several operators manipulate lists.
  522. .DS
  523. list-expression:
  524. primary-expression
  525. \f(CWhead\fP primary-expression
  526. \f(CWtail\fP primary-expression
  527. \f(CWappend\fP expression \f(CW,\fP primary-expression
  528. \f(CWdelete\fP expression \f(CW,\fP primary-expression
  529. .DE
  530. The
  531. .I primary-expression
  532. for
  533. .CW head
  534. and
  535. .CW tail
  536. must yield a value of type
  537. .I list .
  538. If there are no elements in the list the value of
  539. .CW head
  540. or
  541. .CW tail
  542. will be the empty list. Otherwise
  543. .CW head
  544. evaluates to the first element of the list and
  545. .CW tail
  546. evaluates to the rest.
  547. .P1
  548. acid: head {}
  549. {}
  550. acid: head {1, 2, 3, 4}
  551. 0x00000001
  552. acid: tail {1, 2, 3, 4}
  553. {0x00000002 , 0x00000003 , 0x00000004 }
  554. .P2
  555. The first operand of
  556. .CW append
  557. and
  558. .CW delete
  559. must be an expression that yields a
  560. .I list .
  561. .CW Append
  562. places the result of evaluating
  563. .I primary-expression
  564. at the end of the list.
  565. The
  566. .I primary-expression
  567. supplied to
  568. .CW delete
  569. must evaluate to an integer;
  570. .CW delete
  571. removes the
  572. .I n 'th
  573. item from the list, where
  574. .I n
  575. is integral value of
  576. .I primary-expression.
  577. List indices are zero-based.
  578. .P1
  579. acid: append {1, 2}, 3
  580. {0x00000001 , 0x00000002 , 0x00000003 }
  581. acid: delete {1, 2, 3}, 1
  582. {0x00000001 , 0x00000003 }
  583. .P2
  584. .PP
  585. Assigning a list to a variable copies a reference to the list; if a list variable
  586. is copied it still points at the same list. To copy a list, the elements must
  587. be copied piecewise using
  588. .CW head
  589. and
  590. .CW append .
  591. .SH 1
  592. Operators
  593. .PP
  594. .DS
  595. postfix-expression:
  596. list-expression
  597. postfix-expression \f(CW[\fP expression \f(CW]\fP
  598. postfix-expression \f(CW(\fP argument-list \f(CW)\fP
  599. postfix-expression \f(CW.\fP tag
  600. postfix-expression \f(CW->\fP tag
  601. postfix-expression \f(CW++\fP
  602. postfix-expression \f(CW--\fP
  603. argument-list:
  604. expression
  605. argument-list , expression
  606. .DE
  607. The
  608. .CW [
  609. .I expression
  610. .CW ]
  611. operator performs indexing.
  612. The indexing expression must result in an expression of
  613. .I integer
  614. type, say
  615. .I n .
  616. The operation depends on the type of
  617. .I postfix-expression .
  618. If the
  619. .I postfix-expression
  620. yields an
  621. .I integer
  622. it is assumed to be the base address of an array in the memory image.
  623. The index offsets into this array; the size of the array members is
  624. determined by the format associated with the
  625. .I postfix-expression .
  626. If the
  627. .I postfix-expression
  628. yields a
  629. .I string
  630. the index operator fetches the
  631. .I n 'th
  632. character
  633. of the string. If the index points beyond the end
  634. of the string, a zero is returned.
  635. If the
  636. .I postfix-expression
  637. yields a
  638. .I list
  639. then the indexing operation returns the
  640. .I n 'th
  641. item of the list.
  642. If the list contains less than
  643. .I n
  644. items the empty list
  645. .CW {}
  646. is returned.
  647. .PP
  648. The
  649. .CW ++
  650. and
  651. .CW --
  652. operators increment and decrement integer variables.
  653. The amount of increment or decrement depends on the format code. These postfix
  654. operators return the value of the variable before the increment or decrement
  655. has taken place.
  656. .DS
  657. unary-expression:
  658. postfix-expression
  659. \f(CW++\fP unary-expression
  660. \f(CW--\fP unary-expression
  661. unary-operator: one of
  662. \f(CW*\fP \f(CW@\fP \f(CW+\fP \f(CW-\fP ~ \f(CW!\fP
  663. .DE
  664. The operators
  665. .CW *
  666. and
  667. .CW @
  668. are the indirection operators.
  669. .CW @
  670. references a value from the text file of the program being debugged.
  671. The size of the value depends on the format code. The
  672. .CW *
  673. operator fetches a value from the memory image of a process. If either
  674. operator appears on the left-hand side of an assignment statement, either the file
  675. or memory will be written. The file can only be modified when Acid is invoked
  676. with the
  677. .CW -w
  678. option.
  679. The prefix
  680. .CW ++
  681. and
  682. .CW --
  683. operators perform the same operation as their postfix counterparts but
  684. return the value after the increment or decrement has been performed. Since the
  685. .CW ++
  686. and
  687. .CW *
  688. operators fetch and increment the correct amount for the specified format,
  689. the following function prints correct machine instructions on a machine with
  690. variable length instructions, such as the 68020 or 386:
  691. .P1
  692. defn asm(addr)
  693. {
  694. addr = fmt(addr, 'i');
  695. loop 1, 10 do
  696. print(*addr++, "\en");
  697. }
  698. .P2
  699. The operators
  700. .CW ~
  701. and
  702. .CW !
  703. perform bitwise and logical negation respectively. Their operands must be of
  704. .I integer
  705. type.
  706. .DS
  707. cast-expression:
  708. unary-expression
  709. unary-expression \f(CW\e\fP format-char
  710. \f(CW(\fP complex-name \f(CW)\fP unary-expression
  711. .DE
  712. A unary expression may be preceded by a cast. The cast has the effect of
  713. associating the value of
  714. .I unary-expression
  715. with a complex type structure.
  716. The result may then be dereferenced using the
  717. .CW .
  718. and
  719. .CW ->
  720. operators.
  721. .PP
  722. An Acid variable may be associated with a complex type
  723. to enable accessing the type's members:
  724. .P1
  725. acid: complex List {
  726. 'D' 0 type;
  727. 'X' 4 next;
  728. };
  729. acid: complex List lhead
  730. acid: lhead.type
  731. 10
  732. acid: lhead = ((List)lhead).next
  733. acid: lhead.type
  734. -46
  735. .P2
  736. Note that the
  737. .CW next
  738. field cannot be given a complex type automatically.
  739. .PP
  740. When entered at the top level of the interpreter,
  741. an expression of complex type
  742. is treated specially.
  743. If the type is called
  744. .CW T
  745. and an Acid function also called
  746. .CW T
  747. exists,
  748. then that function will be called with the expression as its argument.
  749. The compiler options
  750. .CW -a
  751. and
  752. .CW -aa
  753. will generate Acid source code defining such complex types and functions; see
  754. .I 2c (1).
  755. .PP
  756. A
  757. .I unary-expression
  758. may be qualified with a format specifier using the
  759. .CW \e
  760. operator. This has the same effect as passing the expression to the
  761. .CW fmt
  762. builtin function.
  763. .DS
  764. multiplicative-expression:
  765. cast-expression
  766. multiplicative-expression \f(CW*\fP multiplicative-expression
  767. multiplicative-expression \f(CW/\fP multiplicative-expression
  768. multiplicative-expression \f(CW%\fP multiplicative-expression
  769. .DE
  770. These operate on
  771. .I integer
  772. and
  773. .I float
  774. types and perform the expected operations:
  775. .CW *
  776. multiplication,
  777. .CW /
  778. division,
  779. .CW %
  780. modulus.
  781. .DS
  782. additive-expression:
  783. multiplicative-expression
  784. additive-expression \f(CW+\fP multiplicative-expression
  785. additive-expression \f(CW-\fP multiplicative-expression
  786. .DE
  787. These operators perform as expected for
  788. .I integer
  789. and
  790. .I float
  791. operands.
  792. Unlike in C,
  793. .CW +
  794. and
  795. .CW -
  796. do not scale the addition based on the format of the expression.
  797. This means that
  798. .CW i=i+1
  799. will always add 1 but
  800. .CW i++
  801. will add the size corresponding to the format stored with
  802. .CW i .
  803. If both operands are of either
  804. .I string
  805. or
  806. .I list
  807. type then addition is defined as concatenation.
  808. Adding a string and an integer is treated as concatenation
  809. with the Unicode character corresponding to the integer.
  810. Subtraction is undefined for strings and lists.
  811. .DS
  812. shift-expression:
  813. additive-expression
  814. shift-expression \f(CW<<\fP additive-expression
  815. shift-expression \f(CW>>\fP additive-expression
  816. .DE
  817. The
  818. .CW >>
  819. and
  820. .CW <<
  821. operators perform bitwise right and left shifts respectively. Both
  822. require operands of
  823. .I integer
  824. type.
  825. .DS
  826. relational-expression:
  827. relational-expression \f(CW<\fP shift-expression
  828. relational-expression \f(CW>\fP shift-expression
  829. relational-expression \f(CW<=\fP shift-expression
  830. relational-expression \f(CW>=\fP shift-expression
  831. equality-expression:
  832. relational-expression
  833. relational-expression \f(CW==\fP equality-expression
  834. relational-expression \f(CW!=\fP equality-expression
  835. .DE
  836. The comparison operators are
  837. .CW <
  838. (less than),
  839. .CW >
  840. (greater than),
  841. .CW <=
  842. (less than or equal to),
  843. .CW >=
  844. (greater than or equal to),
  845. .CW ==
  846. (equal to) and
  847. .CW !=
  848. (not equal to). The result of a comparison is 0
  849. if the condition is false, otherwise 1. The relational operators can only be
  850. applied to operands of
  851. .I integer
  852. and
  853. .I float
  854. type. The equality operators apply to all types. Comparing mixed types is legal.
  855. Mixed integer and float compare on the integral value. Other mixtures are always unequal.
  856. Two lists are equal if they
  857. have the same number of members and a pairwise comparison of the members results
  858. in equality.
  859. .DS
  860. AND-expression:
  861. equality-expression
  862. AND-expression \f(CW&\fP equality-expression
  863. XOR-expression:
  864. AND-expression
  865. XOR-expression \f(CW^\fP AND-expression
  866. OR-expression:
  867. XOR-expression
  868. OR-expression \f(CW|\fP XOR-expression
  869. .DE
  870. These operators perform bitwise logical operations and apply only to the
  871. .I integer
  872. type.
  873. The operators are
  874. .CW &
  875. (logical and),
  876. .CW ^
  877. (exclusive or) and
  878. .CW |
  879. (inclusive or).
  880. .DS
  881. logical-AND-expression:
  882. OR-expression
  883. logical-AND-expression \f(CW&&\fP OR-expression
  884. logical-OR-expression:
  885. logical-AND-expression
  886. logical-OR-expression \f(CW||\fP logical-AND-expression
  887. .DE
  888. The
  889. .CW &&
  890. operator returns 1 if both of its operands evaluate to boolean true, otherwise 0.
  891. The
  892. .CW ||
  893. operator returns 1 if either of its operands evaluates to boolean true,
  894. otherwise 0.
  895. .SH
  896. Statements
  897. .PP
  898. .DS
  899. \f(CWif\fP expression \f(CWthen\fP statement \f(CWelse\fP statement
  900. \f(CWif\fP expression \f(CWthen\fP statement
  901. .DE
  902. The
  903. .I expression
  904. is evaluated as a boolean. If its value is true the statement after
  905. the
  906. .CW then
  907. is executed, otherwise the statement after the
  908. .CW else
  909. is executed. The
  910. .CW else
  911. portion may be omitted.
  912. .DS
  913. \f(CWwhile\fP expression \f(CWdo\fP statement
  914. .DE
  915. In a while loop, the
  916. .I statement
  917. is executed while the boolean
  918. .I expression
  919. evaluates
  920. true.
  921. .DS
  922. \f(CWloop\fP startexpr, endexpr \f(CWdo\fP statement
  923. .DE
  924. The two expressions
  925. .I startexpr
  926. and
  927. .I endexpr
  928. are evaluated prior to loop entry.
  929. .I Statement
  930. is evaluated while the value of
  931. .I startexpr
  932. is less than or equal to
  933. .I endexpr .
  934. Both expressions must yield
  935. .I integer
  936. values. The value of
  937. .I startexpr
  938. is
  939. incremented by one for each loop iteration.
  940. Note that there is no explicit loop variable; the
  941. .I expressions
  942. are just values.
  943. .DS
  944. \f(CWreturn\fP expression
  945. .DE
  946. .CW return
  947. terminates execution of the current function and returns to its caller.
  948. The value of the function is given by expression. Since
  949. .CW return
  950. requires an argument, nil-valued functions should return the empty list
  951. .CW {} .
  952. .DS
  953. \f(CWlocal\fP variable
  954. .DE
  955. The
  956. .CW local
  957. statement creates a local instance of
  958. .I variable ,
  959. which exists for the duration
  960. of the instance of the function in which it is declared. Binding is dynamic: the local variable,
  961. rather than the previous value of
  962. .I variable ,
  963. is visible to called functions.
  964. After a return from the current function the previous value of
  965. .I variable
  966. is
  967. restored.
  968. .PP
  969. If Acid is interrupted, the values of all local variables are lost,
  970. as if the function returned.
  971. .DS
  972. \f(CWdefn\fP function-name \f(CW(\fP parameter-list \f(CW)\fP body
  973. parameter-list:
  974. variable
  975. parameter-list , variable
  976. body:
  977. \f(CW{\fP statement \f(CW}\fP
  978. .DE
  979. Functions are introduced by the
  980. .CW defn
  981. statement. The definition of parameter names suppresses any variables
  982. of the same name until the function returns. The body of a function is a list
  983. of statements enclosed by braces.
  984. .SH
  985. Code variables
  986. .PP
  987. Acid permits the delayed evaluation of a parameter to a function. The parameter
  988. may then be evaluated at any time with the
  989. .CW eval
  990. operator. Such parameters are called
  991. .I "code variables
  992. and are defined by prefixing their name with an asterisk in their declaration.
  993. .PP
  994. For example, this function wraps up an expression for later evaluation:
  995. .P1
  996. acid: defn code(*e) { return e; }
  997. acid: x = code(v+atoi("100")\eD)
  998. acid: print(x)
  999. (v+atoi("100"))\eD;
  1000. acid: eval x
  1001. <stdin>:5: (error) v used but not set
  1002. acid: v=5
  1003. acid: eval x
  1004. 105
  1005. .P2
  1006. .SH
  1007. Source Code Management
  1008. .PP
  1009. Acid provides the means to examine source code. Source code is
  1010. represented by lists of strings. Builtin functions provide mapping
  1011. from address to lines and vice-versa. The default debugging environment
  1012. has the means to load and display source files.
  1013. .SH
  1014. Builtin Functions
  1015. .PP
  1016. The Acid interpreter has a number of builtin functions, which cannot be redefined.
  1017. These functions perform machine- or operating system-specific functions such as
  1018. symbol table and process management.
  1019. The following section presents a description of each builtin function.
  1020. The notation
  1021. .CW {}
  1022. is used to denote the empty list, which is the default value of a function that
  1023. does not execute a
  1024. .CW return
  1025. statement.
  1026. The type and number of parameters for each function are specified in the
  1027. description; where a parameter can be of any type it is specified as type
  1028. .I item .
  1029. .de Ip
  1030. .KS
  1031. .in 0
  1032. .LP
  1033. .ie h \&\f2\\$1\fP\ \ \f(CW\\$2(\f2\\$3\f(CW)\f1\ \ \ \ \ \ \ \ \\$4
  1034. .el .tl '\f2\\$1\fP\ \ \f(CW\\$2(\f2\\$3\f(CW)\f1''\\$4'
  1035. .IP
  1036. ..
  1037. .de Ex
  1038. .KE
  1039. .KS
  1040. .IP
  1041. .ft CW
  1042. .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n
  1043. .nf
  1044. .in +4n
  1045. .br
  1046. ..
  1047. .de Ee
  1048. .fi
  1049. .ft 1
  1050. .br
  1051. .KE
  1052. ..
  1053. .\"
  1054. .\"
  1055. .\"
  1056. .Ip integer access string "Check if a file can be read
  1057. .CW Access
  1058. returns the integer 1 if the file name in
  1059. .I string
  1060. can be read by the builtin functions
  1061. .CW file ,
  1062. .CW readfile ,
  1063. or
  1064. .CW include ,
  1065. otherwise 0. A typical use of this function is to follow
  1066. a search path looking for a source file; it is used by
  1067. .CW findsrc .
  1068. .Ex
  1069. if access("main.c") then
  1070. return file("main.c");
  1071. .Ee
  1072. .\"
  1073. .\"
  1074. .\"
  1075. .Ip float atof string "Convert a string to float
  1076. .CW atof
  1077. converts the string supplied as its argument into a floating point
  1078. number. The function accepts strings in the same format as the C
  1079. function of the same name. The value returned has the format code
  1080. .CW f .
  1081. .CW atof
  1082. returns the value 0.0 if it is unable to perform the conversion.
  1083. .Ex
  1084. acid: +atof("10.4e6")
  1085. 1.04e+07
  1086. .Ee
  1087. .\"
  1088. .\"
  1089. .\"
  1090. .Ip integer atoi string "Convert a string to an integer
  1091. .CW atoi
  1092. converts the argument
  1093. .i string
  1094. to an integer value.
  1095. The function accepts strings in the same format as the C function of the
  1096. same name. The value returned has the format code
  1097. .CW D .
  1098. .CW atoi
  1099. returns the integer 0 if it is unable to perform a conversion.
  1100. .Ex
  1101. acid: +atoi("-1255")
  1102. -1255
  1103. .Ee
  1104. .\"
  1105. .\"
  1106. .\"
  1107. .Ip \f(CW{}\fP error string "Generate an interpreter error
  1108. .CW error
  1109. generates an error message and returns the interpreter to interactive
  1110. mode. If an Acid program is running, it is aborted.
  1111. Processes being debugged are not affected. The values of all local variables are lost.
  1112. .CW error
  1113. is commonly used to stop the debugger when some interesting condition arises
  1114. in the debugged program.
  1115. .Ex
  1116. while 1 do {
  1117. step();
  1118. if *main != @main then
  1119. error("memory corrupted");
  1120. }
  1121. .Ee
  1122. .\"
  1123. .\"
  1124. .\"
  1125. .Ip list file string "Read the contents of a file into a list
  1126. .CW file
  1127. reads the contents of the file specified by
  1128. .I string
  1129. into a list.
  1130. Each element in the list is a string corresponding to a line in the file.
  1131. .CW file
  1132. breaks lines at the newline character, but the newline
  1133. characters are not returned as part each string.
  1134. .CW file
  1135. returns the empty list if it encounters an error opening or reading the data.
  1136. .Ex
  1137. acid: print(file("main.c")[0])
  1138. #include <u.h>
  1139. .Ee
  1140. .\"
  1141. .\"
  1142. .\"
  1143. .Ip integer filepc string "Convert source address to text address
  1144. .CW filepc
  1145. interprets its
  1146. .I string
  1147. argument as a source file address in the form of a file name and line offset.
  1148. .CW filepc
  1149. uses the symbol table to map the source address into a text address
  1150. in the debugged program. The
  1151. .I integer
  1152. return value has the format
  1153. .CW X .
  1154. .CW filepc
  1155. returns an address of -1 if the source address is invalid.
  1156. The source file address uses the same format as
  1157. .I acme (1).
  1158. This function is commonly used to set breakpoints from the source text.
  1159. .Ex
  1160. acid: bpset(filepc("main:10"))
  1161. acid: bptab()
  1162. 0x00001020 usage ADD $-0xc,R29
  1163. .Ee
  1164. .\"
  1165. .\"
  1166. .\"
  1167. .Ip item fmt item,fmt "Set print, \f(CW@\fP and \f(CW*\fP formats
  1168. .CW fmt
  1169. evaluates the expression
  1170. .I item
  1171. and sets the format of the result to
  1172. .I fmt .
  1173. The format of a value determines how it will be printed and
  1174. what kind of object will be fetched by the
  1175. .CW *
  1176. and
  1177. .CW @
  1178. operators. The
  1179. .CW \e
  1180. operator is a short-hand form of the
  1181. .CW fmt
  1182. builtin function. The
  1183. .CW fmt
  1184. function leaves the format of the
  1185. .I item
  1186. unchanged.
  1187. .Ex
  1188. acid: main=fmt(main, 'i') // as instructions
  1189. acid: print(main\eX, "\et", *main)
  1190. 0x00001020 ADD $-64,R29
  1191. .Ee
  1192. .\"
  1193. .\"
  1194. .\"
  1195. .Ip fmt fmtof item "Get format
  1196. .CW fmtof
  1197. evaluates the expression
  1198. .I item
  1199. and returns the format of the result.
  1200. .Ex
  1201. acid: +fmtof(33)
  1202. W
  1203. acid: +fmtof("string")
  1204. s
  1205. .Ee
  1206. .\"
  1207. .\"
  1208. .\"
  1209. .Ip integer fmtsize item "Get format size
  1210. .CW fmtsize
  1211. evaluates the expression
  1212. .I item
  1213. and returns the size in bytes of a single element of result's format.
  1214. .Ex
  1215. acid: +fmtsize('c')
  1216. 8
  1217. acid: +fmtsize('c'\ec)
  1218. 1
  1219. acid: +fmtsize(0\eX)
  1220. 4
  1221. acid: +fmtsize('c'\e3)
  1222. 10
  1223. .Ee
  1224. .\"
  1225. .\"
  1226. .\"
  1227. .Ip list fnbound integer "Find start and end address of a function
  1228. .CW fnbound
  1229. interprets its
  1230. .I integer
  1231. argument as an address in the text of the debugged program.
  1232. .CW fnbound
  1233. returns a list containing two integers corresponding to
  1234. the start and end addresses of the function containing the supplied address.
  1235. If the
  1236. .I integer
  1237. address is not in the text segment of the program then the empty list is returned.
  1238. .CW fnbound
  1239. is used by
  1240. .CW next
  1241. to detect stepping into new functions.
  1242. .Ex
  1243. acid: print(fnbound(main))
  1244. {0x00001050, 0x000014b8}
  1245. .Ee
  1246. .\"
  1247. .\"
  1248. .\"
  1249. .Ip \f(CW{}\fP follow integer "Compute follow set
  1250. The follow set is defined as the set of program counter values that could result
  1251. from executing an instruction.
  1252. .CW follow
  1253. interprets its
  1254. .I integer
  1255. argument as a text address, decodes the instruction at
  1256. that address and, with the current register set, builds a list of possible
  1257. next program counter values. If the instruction at the specified address
  1258. cannot be decoded
  1259. .CW follow
  1260. raises an error.
  1261. .CW follow
  1262. is used to plant breakpoints on
  1263. all potential paths of execution. The following code fragment
  1264. plants breakpoints on top of all potential following instructions.
  1265. .Ex
  1266. lst = follow(*PC);
  1267. while lst do
  1268. {
  1269. *head lst = bpinst;
  1270. lst = tail lst;
  1271. }
  1272. .Ee
  1273. .\"
  1274. .\"
  1275. .\"
  1276. .Ip \f(CW{}\fP include string "Take input from a new file
  1277. .CW include
  1278. opens the file specified by
  1279. .I string
  1280. and uses its contents as command input to the interpreter.
  1281. The interpreter restores input to its previous source when it encounters
  1282. either an end of file or an error.
  1283. .CW include
  1284. can be used to incrementally load symbol table information without
  1285. leaving the interpreter.
  1286. .Ex
  1287. acid: include("/sys/src/cmd/acme/syms")
  1288. .Ee
  1289. .\"
  1290. .\"
  1291. .\"
  1292. .Ip \f(CW{}\fP interpret string "Take input from a string
  1293. .CW interpret
  1294. evaluates the
  1295. .I string
  1296. expression and uses its result as command input for the interpreter.
  1297. The interpreter restores input to its previous source when it encounters
  1298. either the end of string or an error. The
  1299. .CW interpret
  1300. function allows Acid programs to write Acid code for later evaluation.
  1301. .Ex
  1302. acid: interpret("main+10;")
  1303. 0x0000102a
  1304. .Ee
  1305. .\"
  1306. .\"
  1307. .\"
  1308. .Ip string itoa integer[,string] "Convert integer to string
  1309. .CW itoa
  1310. takes an integer argument and converts it into an ASCII string
  1311. in the
  1312. .CW D
  1313. format.
  1314. an alternate format string
  1315. may be provided in the
  1316. .CW %
  1317. style of
  1318. .I print (2).
  1319. This function is commonly used to build
  1320. .CW rc
  1321. command lines.
  1322. .Ex
  1323. acid: rc("cat /proc/"+itoa(pid)+"/segment")
  1324. Stack 7fc00000 80000000 1
  1325. Data 00001000 00009000 1
  1326. Data 00009000 0000a000 1
  1327. Bss 0000a000 0000c000 1
  1328. .Ee
  1329. .\"
  1330. .\"
  1331. .\"
  1332. .Ip \f(CW{}\fP kill integer "Kill a process
  1333. .CW kill
  1334. writes a kill control message into the control file of the process
  1335. specified by the
  1336. .I integer
  1337. pid.
  1338. If the process was previously installed by
  1339. .CW setproc
  1340. it will be removed from the list of active processes.
  1341. If the
  1342. .I integer
  1343. has the same value as
  1344. .CW pid ,
  1345. then
  1346. .CW pid
  1347. will be set to 0.
  1348. To continue debugging, a new process must be selected using
  1349. .CW setproc .
  1350. For example, to kill all the active processes:
  1351. .Ex
  1352. while proclist do {
  1353. kill(head proclist);
  1354. proclist = tail proclist;
  1355. }
  1356. .Ee
  1357. .\"
  1358. .\"
  1359. .\"
  1360. .Ip list map list "Set or retrieve process memory map
  1361. .CW map
  1362. either retrieves all the mappings associated with a process or sets a single
  1363. map entry to a new value.
  1364. If the
  1365. .I list
  1366. argument is omitted then
  1367. .CW map
  1368. returns a list of lists. Each sublist has four values and describes a
  1369. single region of contiguous addresses in the
  1370. memory or file image of the debugged program. The first entry is the name of the
  1371. mapping. If the name begins with
  1372. .CW *
  1373. it denotes a map into the memory of an active process.
  1374. The second and third values specify the base and end
  1375. address of the region and the fourth number specifies the offset in the file
  1376. corresponding to the first location of the region.
  1377. A map entry may be set by supplying a list in the same format as the sublist
  1378. described above. The name of the mapping must match a region already defined
  1379. by the current map.
  1380. Maps are set automatically for Plan 9 processes and some kernels; they may
  1381. need to be set by hand for other kernels and programs that run on bare hardware.
  1382. .Ex
  1383. acid: map({"text", _start, end, 0x30})
  1384. .Ee
  1385. .\"
  1386. .\"
  1387. .\"
  1388. .Ip integer match item,list "Search list for matching value
  1389. .CW match
  1390. compares each item in
  1391. .I list
  1392. using the equality operator
  1393. .CW ==
  1394. with
  1395. .I item .
  1396. The
  1397. .I item
  1398. can be of any type. If the match succeeds the result is the integer index
  1399. of the matching value, otherwise -1.
  1400. .Ex
  1401. acid: list={8,9,10,11}
  1402. acid: print(list[match(10, list)]\eD)
  1403. 10
  1404. .Ee
  1405. .\"
  1406. .\"
  1407. .\"
  1408. .Ip \f(CW{}\fP newproc string "Create a new process
  1409. .CW newproc
  1410. starts a new process with an argument vector constructed from
  1411. .I string .
  1412. The argument vector excludes the name of the program to execute and
  1413. each argument in
  1414. .I string
  1415. must be space separated. A new process can accept no more
  1416. than 512 arguments. The internal variable
  1417. .CW pid
  1418. is set to the pid of the newly created process. The new pid
  1419. is also appended to the list of active processes stored in the variable
  1420. .CW proclist .
  1421. The new process is created then halted at the first instruction, causing
  1422. the debugger to call
  1423. .CW stopped .
  1424. The library functions
  1425. .CW new
  1426. and
  1427. .CW win
  1428. should be used to start processes when using the standard debugging
  1429. environment.
  1430. .Ex
  1431. acid: newproc("-l .")
  1432. 56720: system call _main ADD $-0x14,R29
  1433. .Ee
  1434. .\"
  1435. .\"
  1436. .\"
  1437. .Ip string pcfile integer "Convert text address to source file name
  1438. .CW pcfile
  1439. interprets its
  1440. .I integer
  1441. argument as a text address in the debugged program. The address and symbol table
  1442. are used to generate a string containing the name of the source file
  1443. corresponding to the text address. If the address does not lie within the
  1444. program the string
  1445. .CW ?file?
  1446. is returned.
  1447. .Ex
  1448. acid: print("Now at ", pcfile(*PC), ":", pcline(*PC))
  1449. Now at ls.c:46
  1450. .Ee
  1451. .\"
  1452. .\"
  1453. .\"
  1454. .Ip integer pcline integer "Convert text address to source line number
  1455. .CW pcline
  1456. interprets its
  1457. .I integer
  1458. argument as a text address in the debugged program. The address and symbol table
  1459. are used to generate an integer containing the line number in the source file
  1460. corresponding to the text address. If the address does not lie within the
  1461. program the integer 0 is returned.
  1462. .Ex
  1463. acid: +file("main.c")[pcline(main)]
  1464. main(int argc, char *argv[])
  1465. .Ee
  1466. .\"
  1467. .\"
  1468. .\"
  1469. .Ip \f(CW{}\fP print item,item,... "Print expressions
  1470. .CW print
  1471. evaluates each
  1472. .I item
  1473. supplied in its argument list and prints it to standard output. Each
  1474. argument will be printed according to its associated format character.
  1475. When the interpreter is executing, output is buffered and flushed every
  1476. 5000 statements or when the interpreter returns to interactive mode.
  1477. .CW print
  1478. accepts a maximum of 512 arguments.
  1479. .Ex
  1480. acid: print(10, "decimal ", 10\eD, "octal ", 10\eo)
  1481. 0x0000000a decimal 10 octal 000000000012
  1482. acid: print({1, 2, 3})
  1483. {0x00000001 , 0x00000002 , 0x00000003 }
  1484. acid: print(main, main\ea, "\et", @main\ei)
  1485. 0x00001020 main ADD $-64,R29
  1486. .Ee
  1487. .\"
  1488. .\"
  1489. .\"
  1490. .Ip \f(CW{}\fP printto string,item,item,... "Print expressions to file
  1491. .CW printto
  1492. offers a limited form of output redirection. The first
  1493. .I string
  1494. argument is used as the path name of a new file to create.
  1495. Each
  1496. .I item
  1497. is then evaluated and printed to the newly created file. When all items
  1498. have been printed the file is closed.
  1499. .CW printto
  1500. accepts a maximum of 512 arguments.
  1501. .Ex
  1502. acid: printto("/env/foo", "hello")
  1503. acid: rc("echo -n $foo")
  1504. hello
  1505. .Ee
  1506. .\"
  1507. .\"
  1508. .\"
  1509. .Ip string rc string "Execute a shell command
  1510. .CW rc
  1511. evaluates
  1512. .I string
  1513. to form a shell command. A new command interpreter is started
  1514. to execute the command. The Acid interpreter blocks until the command
  1515. completes. The return value is the empty string
  1516. if the command succeeds, otherwise the exit status of the failed command.
  1517. .Ex
  1518. acid: rc("B "+itoa(-pcline(addr))+" "+pcfile(addr));
  1519. .Ee
  1520. .\"
  1521. .\"
  1522. .\"
  1523. .Ip string readfile string "Read file contents into a string
  1524. .CW readfile
  1525. takes the contents of the file specified by
  1526. .I string
  1527. and returns its contents as a new string.
  1528. If
  1529. .CW readfile
  1530. encounters a zero byte in the file, it terminates.
  1531. If
  1532. .CW readfile
  1533. encounters an error opening or reading the file then the empty list
  1534. is returned.
  1535. .CW readfile
  1536. can be used to read the contents of device files whose lines are not
  1537. terminated with newline characters.
  1538. .Ex
  1539. acid: ""+readfile("/dev/label")
  1540. helix
  1541. .Ee
  1542. .\"
  1543. .\"
  1544. .\"
  1545. .Ip string reason integer "Print cause of program stoppage
  1546. .CW reason
  1547. uses machine-dependent information to generate a string explaining
  1548. why a process has stopped. The
  1549. .I integer
  1550. argument is the value of an architecture dependent status register,
  1551. for example
  1552. .CW CAUSE
  1553. on the MIPS.
  1554. .Ex
  1555. acid: print(reason(*CAUSE))
  1556. system call
  1557. .Ee
  1558. .\"
  1559. .\"
  1560. .\"
  1561. .Ip integer regexp pattern,string "Regular expression match
  1562. .CW regexp
  1563. matches the
  1564. .I pattern
  1565. string supplied as its first argument with the
  1566. .I string
  1567. supplied as its second.
  1568. If the pattern matches the result is the value 1, otherwise 0.
  1569. .Ex
  1570. acid: print(regexp(".*bar", "foobar"))
  1571. 1
  1572. .Ee
  1573. .\"
  1574. .\"
  1575. .\"
  1576. .Ip \f(CW{}\fP setproc integer "Set debugger focus
  1577. .CW setproc
  1578. selects the default process used for memory and control operations. It effectively
  1579. shifts the focus of control between processes. The
  1580. .I integer
  1581. argument specifies the pid of the process to look at.
  1582. The variable
  1583. .CW pid
  1584. is set to the pid of the selected process. If the process is being
  1585. selected for the first time its pid is added to the list of active
  1586. processes
  1587. .CW proclist .
  1588. .Ex
  1589. acid: setproc(68382)
  1590. acid: procs()
  1591. >68382: Stopped at main+0x4 setproc(68382)
  1592. .Ee
  1593. .\"
  1594. .\"
  1595. .\"
  1596. .Ip \f(CW{}\fP start integer "Restart execution
  1597. .CW start
  1598. writes a
  1599. .CW start
  1600. message to the control file of the process specified by the pid
  1601. supplied as its
  1602. .I integer
  1603. argument.
  1604. .CW start
  1605. draws an error if the process is not in the
  1606. .CW Stopped
  1607. state.
  1608. .Ex
  1609. acid: start(68382)
  1610. acid: procs()
  1611. >68382: Running at main+0x4 setproc(68382)
  1612. .Ee
  1613. .\"
  1614. .\"
  1615. .\"
  1616. .Ip \f(CW{}\fP startstop integer "Restart execution, block until stopped
  1617. .CW startstop
  1618. performs the same actions as a call to
  1619. .CW start
  1620. followed by a call to
  1621. .CW stop .
  1622. The
  1623. .I integer
  1624. argument specifies the pid of the process to control. The process
  1625. must be in the
  1626. .CW Stopped
  1627. state.
  1628. Execution is restarted, the debugger then waits for the process to
  1629. return to the
  1630. .CW Stopped
  1631. state. A process will stop if a startstop message has been written to its control
  1632. file and any of the following conditions becomes true: the process executes or returns from
  1633. a system call, the process generates a trap or the process receives a note.
  1634. .CW startstop
  1635. is used to implement single stepping.
  1636. .Ex
  1637. acid: startstop(pid)
  1638. 75374: breakpoint ls ADD $-0x16c8,R29
  1639. .Ee
  1640. .\"
  1641. .\"
  1642. .\"
  1643. .Ip string status integer "Return process state
  1644. .CW status
  1645. uses the pid supplied by its
  1646. .I integer
  1647. argument to generate a string describing the state of the process.
  1648. The string corresponds to the state returned by the
  1649. sixth column of the
  1650. .I ps (1)
  1651. command.
  1652. A process must be in the
  1653. .CW Stopped
  1654. state to modify its memory or registers.
  1655. .Ex
  1656. acid: ""+status(pid)
  1657. Stopped
  1658. .Ee
  1659. .\"
  1660. .\"
  1661. .\"
  1662. .Ip \f(CW{}\fP stop integer "Wait for a process to stop
  1663. .CW stop
  1664. writes a
  1665. .CW stop
  1666. message to the control file of the process specified by the
  1667. pid supplied as its
  1668. .I integer
  1669. argument.
  1670. The interpreter blocks until the debugged process enters the
  1671. .CW Stopped
  1672. state.
  1673. A process will stop if a stop message has been written to its control
  1674. file and any of the following conditions becomes true: the process executes or returns from
  1675. a system call, the process generates a trap, the process is scheduled or the
  1676. process receives a note.
  1677. .CW stop
  1678. is used to wait for a process to halt before planting a breakpoint since Plan 9
  1679. only allows a process's memory to be written while it is in the
  1680. .CW Stopped
  1681. state.
  1682. .Ex
  1683. defn bpset(addr) {
  1684. if (status(pid)!="Stopped") then {
  1685. print("Waiting...\en");
  1686. stop(pid);
  1687. }
  1688. ...
  1689. }
  1690. .Ee
  1691. .\"
  1692. .\"
  1693. .\"
  1694. .Ip list strace pc,sp,linkreg "Stack trace
  1695. .CW strace
  1696. generates a list of lists corresponding to procedures called by the debugged
  1697. program. Each sublist describes a single stack frame in the active process.
  1698. The first element is an
  1699. .I integer
  1700. of format
  1701. .CW X
  1702. specifying the address of the called function. The second element is the value
  1703. of the program counter when the function was called. The third and fourth elements
  1704. contain lists of parameter and automatic variables respectively.
  1705. Each element of these lists
  1706. contains a string with the name of the variable and an
  1707. .I integer
  1708. value of format
  1709. .CW X
  1710. containing the current value of the variable.
  1711. The arguments to
  1712. .CW strace
  1713. are the current value of the program counter, the current value of the
  1714. stack pointer, and the address of the link register. All three parameters
  1715. must be integers.
  1716. The setting of
  1717. .I linkreg
  1718. is architecture dependent. On the MIPS linkreg is set to the address of saved
  1719. .CW R31 ,
  1720. on the SPARC to the address of saved
  1721. .CW R15 .
  1722. For the other architectures
  1723. .I linkreg
  1724. is not used, but must point to valid memory.
  1725. .Ex
  1726. acid: print(strace(*PC, *SP, linkreg))
  1727. {{0x0000141c, 0xc0000f74,
  1728. {{"s", 0x0000004d}, {"multi", 0x00000000}},
  1729. {{"db", 0x00000000}, {"fd", 0x000010a4},
  1730. {"n", 0x00000001}, {"i", 0x00009824}}}}
  1731. .Ee
  1732. .\"
  1733. .\"
  1734. .\"
  1735. .Ip \f(CW{}\fP waitstop integer "Wait for a process to stop
  1736. .CW waitstop
  1737. writes a waitstop message to the control file of the process specified by the
  1738. pid supplied as its
  1739. .I integer
  1740. argument.
  1741. The interpreter will remain blocked until the debugged process enters the
  1742. .CW Stopped
  1743. state.
  1744. A process will stop if a waitstop message has been written to its control
  1745. file and any of the following conditions becomes true: the process generates a trap
  1746. or receives a note. Unlike
  1747. .CW stop ,
  1748. the
  1749. .CW waitstop
  1750. function is passive; it does not itself cause the program to stop.
  1751. .Ex
  1752. acid: waitstop(pid)
  1753. 75374: breakpoint ls ADD $-0x16c8,R29
  1754. .Ee
  1755. .\"
  1756. .\"
  1757. .\"
  1758. .SH
  1759. Library Functions
  1760. .PP
  1761. A standard debugging environment is provided by modules automatically
  1762. loaded when
  1763. Acid is started.
  1764. These modules are located in the directory
  1765. .CW /sys/lib/acid .
  1766. These functions may be overridden, personalized, or added to by code defined in
  1767. .CW $home/lib/acid .
  1768. The implementation of these functions can be examined using the
  1769. .CW whatis
  1770. operator and then modified during debugging sessions.
  1771. .\"
  1772. .\"
  1773. .\"
  1774. .Ip \f(CW{}\fP Bsrc integer "Load editor with source
  1775. .CW Bsrc
  1776. interprets the
  1777. .I integer
  1778. argument as a text address. The text address is used to produce a pathname
  1779. and line number suitable for the
  1780. .CW B
  1781. command
  1782. to send to the text editor
  1783. .I sam (1)
  1784. or
  1785. .I acme (1).
  1786. .CW Bsrc
  1787. builds an
  1788. .I rc (1)
  1789. command to invoke
  1790. .CW B ,
  1791. which either selects an existing source file or loads a new source file into the editor.
  1792. The line of source corresponding to the text address is then selected.
  1793. In the following example
  1794. .CW stopped
  1795. is redefined so that the editor
  1796. follows and displays the source line currently being executed.
  1797. .Ex
  1798. defn stopped(pid) {
  1799. pstop(pid);
  1800. Bsrc(*PC);
  1801. }
  1802. .Ee
  1803. .\"
  1804. .\"
  1805. .\"
  1806. .Ip \f(CW{}\fP Fpr "" "Display double precision floating registers
  1807. For machines equipped with floating point,
  1808. .CW Fpr
  1809. displays the contents of the floating point registers as double precision
  1810. values.
  1811. .Ex
  1812. acid: Fpr()
  1813. F0 0. F2 0.
  1814. F4 0. F6 0.
  1815. F8 0. F10 0.
  1816. \&...
  1817. .Ee
  1818. .\"
  1819. .\"
  1820. .\"
  1821. .Ip \f(CW{}\fP Ureg integer "Display contents of Ureg structure
  1822. .CW Ureg
  1823. interprets the integer passed as its first argument as the address of a
  1824. kernel
  1825. .CW Ureg
  1826. structure. Each element of the structure is retrieved and printed.
  1827. The size and contents of the
  1828. .CW Ureg
  1829. structure are architecture dependent.
  1830. This function can be used to decode the first argument passed to a
  1831. .I notify (2)
  1832. function after a process has received a note.
  1833. .Ex
  1834. acid: Ureg(*notehandler:ur)
  1835. status 0x3000f000
  1836. pc 0x1020
  1837. sp 0x7ffffe00
  1838. cause 0x00004002
  1839. \&...
  1840. .Ee
  1841. .\"
  1842. .\"
  1843. .\"
  1844. .Ip \f(CW{}\fP acidinit "" "Interpreter startup
  1845. .CW acidinit
  1846. is called by the interpreter after all
  1847. modules have been loaded at initialization time.
  1848. It is used to set up machine specific variables and the default source path.
  1849. .CW acidinit
  1850. should not be called by user code.
  1851. .KE
  1852. .\"
  1853. .\"
  1854. .\"
  1855. .Ip \f(CW{}\fP addsrcdir string "Add element to source search path
  1856. .CW addsrcdir
  1857. interprets its string argument as a new directory
  1858. .CW findsrc
  1859. should search when looking for source code files.
  1860. .CW addsrcdir
  1861. draws an error if the directory is already in the source search path. The search
  1862. path may be examined by looking at the variable
  1863. .CW srcpath .
  1864. .Ex
  1865. acid: rc("9fs fornax")
  1866. acid: addsrcpath("/n/fornax/sys/src/cmd")
  1867. .Ee
  1868. .\"
  1869. .\"
  1870. .\"
  1871. .Ip \f(CW{}\fP asm integer "Disassemble machine instructions
  1872. .CW asm
  1873. interprets its integer argument as a text address from which to disassemble
  1874. machine instructions.
  1875. .CW asm
  1876. prints the instruction address in symbolic and hexadecimal form, then prints
  1877. the instructions with addressing modes. Up to twenty instructions will
  1878. be disassembled.
  1879. .CW asm
  1880. stops disassembling when it reaches the end of the current function.
  1881. Instructions are read from the file image using the
  1882. .CW @
  1883. operator.
  1884. .Ex
  1885. acid: asm(main)
  1886. main 0x00001020 ADD $-0x64,R29
  1887. main+0x4 0x00001024 MOVW R31,0x0(R29)
  1888. main+0x8 0x00001028 MOVW R1,argc+4(FP)
  1889. main+0xc 0x0000102c MOVW $bin(SB),R1
  1890. .Ee
  1891. .\"
  1892. .\"
  1893. .\"
  1894. .Ip \f(CW{}\fP bpdel integer "Delete breakpoint
  1895. .CW bpdel
  1896. removes a previously set breakpoint from memory.
  1897. The
  1898. .I integer
  1899. supplied as its argument must be the address of a previously set breakpoint.
  1900. The breakpoint address is deleted from the active breakpoint list
  1901. .CW bplist ,
  1902. then the original instruction is copied from the file image to the memory
  1903. image so that the breakpoint is removed.
  1904. .Ex
  1905. acid: bpdel(main+4)
  1906. .Ee
  1907. .\"
  1908. .\"
  1909. .\"
  1910. .Ip \f(CW{}\fP bpset integer "Set a breakpoint
  1911. .CW bpset
  1912. places a breakpoint instruction at the address specified
  1913. by its
  1914. .I integer
  1915. argument, which must be in the text segment.
  1916. .CW bpset
  1917. draws an error if a breakpoint has already been set at the specified address.
  1918. A list of current breakpoints is maintained in the variable
  1919. .CW bplist .
  1920. Unlike in
  1921. .I db (1),
  1922. breakpoints are left in memory even when a process is stopped, and
  1923. the process must exist, perhaps by being
  1924. created by either
  1925. .CW new
  1926. or
  1927. .CW win ,
  1928. in order to place a breakpoint.
  1929. .CW Db "" (
  1930. accepts breakpoint commands before the process is started.)
  1931. On the
  1932. MIPS and SPARC architectures,
  1933. breakpoints at function entry points should be set 4 bytes into the function
  1934. because the
  1935. instruction scheduler may fill
  1936. .CW JAL
  1937. branch delay slots with the first instruction of the function.
  1938. .Ex
  1939. acid: bpset(main+4)
  1940. .Ee
  1941. .\"
  1942. .\"
  1943. .\"
  1944. .Ip \f(CW{}\fP bptab "" "List active breakpoints
  1945. .CW bptab
  1946. prints a list of currently installed breakpoints. The list contains the
  1947. breakpoint address in symbolic and hexadecimal form as well as the instruction
  1948. the breakpoint replaced. Breakpoints are not maintained across process creation
  1949. using
  1950. .CW new
  1951. and
  1952. .CW win .
  1953. They are maintained across a fork, but care must be taken to keep control of
  1954. the child process.
  1955. .Ex
  1956. acid: bpset(ls+4)
  1957. acid: bptab()
  1958. 0x00001420 ls+0x4 MOVW R31,0x0(R29)
  1959. .Ee
  1960. .\"
  1961. .\"
  1962. .\"
  1963. .Ip \f(CW{}\fP casm "" "Continue disassembly
  1964. .CW casm
  1965. continues to disassemble instructions from where the last
  1966. .CW asm
  1967. or
  1968. .CW casm
  1969. command stopped. Like
  1970. .CW asm ,
  1971. this command stops disassembling at function boundaries.
  1972. .Ex
  1973. acid: casm()
  1974. main+0x10 0x00001030 MOVW $0x1,R3
  1975. main+0x14 0x00001034 MOVW R3,0x8(R29)
  1976. main+0x18 0x00001038 MOVW $0x1,R5
  1977. main+0x1c 0x0000103c JAL Binit(SB)
  1978. .Ee
  1979. .\"
  1980. .\"
  1981. .\"
  1982. .Ip \f(CW{}\fP cont "" "Continue program execution
  1983. .CW cont
  1984. restarts execution of the currently active process.
  1985. If the process is stopped on a breakpoint, the breakpoint is first removed,
  1986. the program is single stepped, the breakpoint is replaced and the program
  1987. is then set executing. This may cause
  1988. .CW stopped()
  1989. to be called twice.
  1990. .CW cont
  1991. causes the interpreter to block until the process enters the
  1992. .CW Stopped
  1993. state.
  1994. .Ex
  1995. acid: cont()
  1996. 95197: breakpoint ls+0x4 MOVW R31,0x0(R29)
  1997. .Ee
  1998. .\"
  1999. .\"
  2000. .\"
  2001. .Ip \f(CW{}\fP dump integer,integer,string "Formatted memory dump
  2002. .CW dump
  2003. interprets its first argument as an address, its second argument as a
  2004. count and its third as a format string.
  2005. .CW dump
  2006. fetches an object from memory at the current address and prints it according
  2007. to the format. The address is incremented by the number of bytes specified by
  2008. the format and the process is repeated count times. The format string is any
  2009. combination of format characters, each preceded by an optional count.
  2010. For each object,
  2011. .CW dump
  2012. prints the address in hexadecimal, a colon, the object and then a newline.
  2013. .CW dump
  2014. uses
  2015. .CW mem
  2016. to fetch each object.
  2017. .Ex
  2018. acid: dump(main+35, 4, "X2bi")
  2019. 0x00001043: 0x0c8fa700 108 143 lwc2 r0,0x528f(R4)
  2020. 0x0000104d: 0xa9006811 0 0 swc3 r0,0x0(R24)
  2021. 0x00001057: 0x2724e800 4 37 ADD $-0x51,R23,R31
  2022. 0x00001061: 0xa200688d 6 0 NOOP
  2023. 0x0000106b: 0x2710c000 7 0 BREAK
  2024. .Ee
  2025. .\"
  2026. .\"
  2027. .\"
  2028. .Ip \f(CW{}\fP findsrc string "Use source path to load source file
  2029. .CW findsrc
  2030. interprets its
  2031. .I string
  2032. argument as a source file. Each directory in the source path is searched
  2033. in turn for the file. If the file is found, the source text is loaded using
  2034. .CW file
  2035. and stored in the list of active source files called
  2036. .CW srctext .
  2037. The name of the file is added to the source file name list
  2038. .CW srcfiles .
  2039. Users are unlikely to call
  2040. .CW findsrc
  2041. from the command line, but may use it from scripts to preload source files
  2042. for a debugging session. This function is used by
  2043. .CW src
  2044. and
  2045. .CW line
  2046. to locate and load source code. The default search path for the MIPS
  2047. is
  2048. .CW ./ ,
  2049. .CW /sys/src/libc/port ,
  2050. .CW /sys/src/libc/9sys ,
  2051. .CW /sys/src/libc/mips .
  2052. .Ex
  2053. acid: findsrc(pcfile(main));
  2054. .Ee
  2055. .\"
  2056. .\"
  2057. .\"
  2058. .Ip \f(CW{}\fP fpr "" "Display single precision floating registers
  2059. For machines equipped with floating point,
  2060. .CW fpr
  2061. displays the contents of the floating point registers as single precision
  2062. values. When the interpreter stores or manipulates floating point values
  2063. it converts into double precision values.
  2064. .Ex
  2065. acid: fpr()
  2066. F0 0. F1 0.
  2067. F2 0. F3 0.
  2068. F4 0. F5 0.
  2069. \&...
  2070. .Ee
  2071. .\"
  2072. .\"
  2073. .\"
  2074. .Ip \f(CW{}\fP func "" "Step while in function
  2075. .CW func
  2076. single steps the active process until it leaves the current function
  2077. by either calling another function or returning to its caller.
  2078. .CW func
  2079. will execute a single instruction after leaving the current function.
  2080. .Ex
  2081. acid: func()
  2082. 95197: breakpoint ls+0x8 MOVW R1,R8
  2083. 95197: breakpoint ls+0xc MOVW R8,R1
  2084. 95197: breakpoint ls+0x10 MOVW R8,s+4(FP)
  2085. 95197: breakpoint ls+0x14 MOVW $0x2f,R5
  2086. 95197: breakpoint ls+0x18 JAL utfrrune(SB)
  2087. 95197: breakpoint utfrrune ADD $-0x18,R29
  2088. .Ee
  2089. .\"
  2090. .\"
  2091. .\"
  2092. .Ip \f(CW{}\fP gpr "" "Display general purpose registers
  2093. .CW gpr
  2094. prints the values of the general purpose processor registers.
  2095. .Ex
  2096. acid: gpr()
  2097. R1 0x00009562 R2 0x000010a4 R3 0x00005d08
  2098. R4 0x0000000a R5 0x0000002f R6 0x00000008
  2099. \&...
  2100. .Ee
  2101. .\"
  2102. .\"
  2103. .\"
  2104. .Ip \f(CW{}\fP labstk integer "Print stack trace from label
  2105. .CW labstk
  2106. performs a stack trace from a Plan 9
  2107. .I label.
  2108. The kernel,
  2109. C compilers store continuations in a common format. Since the
  2110. compilers all use caller save conventions a continuation may be saved by
  2111. storing a
  2112. .CW PC
  2113. and
  2114. .CW SP
  2115. pair. This data structure is called a label and is used by the
  2116. the C function
  2117. .CW longjmp
  2118. and the kernel to schedule threads and processes.
  2119. .CW labstk
  2120. interprets its
  2121. .I integer
  2122. argument as the address of a label and produces a stack trace for
  2123. the thread of execution. The value of the function
  2124. .CW ALEF_tid
  2125. is a suitable argument for
  2126. .CW labstk .
  2127. .Ex
  2128. acid: labstk(*mousetid)
  2129. At pc:0x00021a70:Rendez_Sleep+0x178 rendez.l:44
  2130. Rendez_Sleep(r=0xcd7d8,bool=0xcd7e0,t=0x0) rendez.l:5
  2131. called from ALEF_rcvmem+0x198 recvmem.l:45
  2132. ALEF_rcvmem(c=0x000cd764,l=0x00000010) recvmem.l:6
  2133. \&...
  2134. .Ee
  2135. .\"
  2136. .\"
  2137. .\"
  2138. .Ip \f(CW{}\fP lstk "" "Stack trace with local variables
  2139. .CW lstk
  2140. produces a long format stack trace.
  2141. The stack trace includes each function in the stack,
  2142. where it was called from, and the value of the parameters and automatic
  2143. variables for each function.
  2144. .CW lstk
  2145. displays the value rather than the address of each variable and all
  2146. variables are assumed to be an integer in format
  2147. .CW X .
  2148. To print a variable in its correct format use the
  2149. .CW :
  2150. operator to find the address and apply the appropriate format before indirection
  2151. with the
  2152. .CW *
  2153. operator. It may be necessary to single step a couple of instructions into
  2154. a function to get a correct stack trace because the frame pointer adjustment
  2155. instruction may get scheduled down into the body of the function.
  2156. .Ex
  2157. acid: lstk()
  2158. At pc:0x00001024:main+0x4 ls.c:48
  2159. main(argc=0x00000001,argv=0x7fffefec) ls.c:48
  2160. called from _main+0x20 main9.s:10
  2161. _argc=0x00000000
  2162. _args=0x00000000
  2163. fd=0x00000000
  2164. buf=0x00000000
  2165. i=0x00000000
  2166. .Ee
  2167. .\"
  2168. .\"
  2169. .\"
  2170. .Ip \f(CW{}\fP mem integer,string "Print memory object
  2171. .CW mem
  2172. interprets its first
  2173. .I integer
  2174. argument as the address of an object to be printed according to the
  2175. format supplied in its second
  2176. .I string
  2177. argument.
  2178. The format string can be any combination of format characters, each preceded
  2179. by an optional count.
  2180. .Ex
  2181. acid: mem(bdata+0x326, "2c2Xb")
  2182. P = 0xa94bc464 0x3e5ae44d 19
  2183. .Ee
  2184. .\"
  2185. .\"
  2186. .\"
  2187. .Ip \f(CW{}\fP new "" "Create new process
  2188. .CW new
  2189. starts a new copy of the debugged program. The new program is started
  2190. with the program arguments set by the variable
  2191. .CW progargs .
  2192. The new program is stopped in the second instruction of
  2193. .CW main .
  2194. The breakpoint list is reinitialized.
  2195. .CW new
  2196. may be used several times to instantiate several copies of a program
  2197. simultaneously. The user can rotate between the copies using
  2198. .CW setproc .
  2199. .Ex
  2200. acid: progargs="-l"
  2201. acid: new()
  2202. 60: external interrupt _main ADD $-0x14,R29
  2203. 60: breakpoint main+0x4 MOVW R31,0x0(R29)
  2204. .Ee
  2205. .\"
  2206. .\"
  2207. .\"
  2208. .Ip \f(CW{}\fP next "" "Step through language statement
  2209. .CW next
  2210. steps through a single language level statement without tracing down
  2211. through each statement in a called function. For each statement,
  2212. .CW next
  2213. prints the machine instructions executed as part of the statement. After
  2214. the statement has executed, source lines around the current program
  2215. counter are displayed.
  2216. .Ex
  2217. acid: next()
  2218. 60: breakpoint Binit+0x4 MOVW R31,0x0(R29)
  2219. 60: breakpoint Binit+0x8 MOVW f+8(FP),R4
  2220. binit.c:93
  2221. 88
  2222. 89 int
  2223. 90 Binit(Biobuf *bp, int f, int mode)
  2224. 91 {
  2225. >92 return Binits(bp, f, mode, bp->b, BSIZE);
  2226. 93 }
  2227. .Ee
  2228. .\"
  2229. .\"
  2230. .\"
  2231. .Ip \f(CW{}\fP notestk integer "Stack trace after receiving a note
  2232. .CW notestk
  2233. interprets its
  2234. .I integer
  2235. argument as the address of a
  2236. .CW Ureg
  2237. structure passed by the kernel to a
  2238. .I notify (2)
  2239. function during note processing.
  2240. .CW notestk
  2241. uses the
  2242. .CW PC ,
  2243. .CW SP ,
  2244. and link register from the
  2245. .CW Ureg
  2246. to print a stack trace corresponding to the point in the program where the note
  2247. was received.
  2248. To get a valid stack trace on the MIPS and SPARC architectures from a notify
  2249. routine, the program must stop in a new function called from the notify routine
  2250. so that the link register is valid and the notify routine's parameters are
  2251. addressable.
  2252. .Ex
  2253. acid: notestk(*notify:ur)
  2254. Note pc:0x00001024:main+0x4 ls.c:48
  2255. main(argc=0x00000001,argv=0x7fffefec) ls.c:48
  2256. called from _main+0x20 main9.s:10
  2257. _argc=0x00000000
  2258. _args=0x00000000
  2259. .Ee
  2260. .\"
  2261. .\"
  2262. .\"
  2263. .Ip \f(CW{}\fP pfl integer "Print source file and line
  2264. .CW pfl
  2265. interprets its argument as a text address and uses it to print
  2266. the source file and line number corresponding to the address. The output
  2267. has the same format as file addresses in
  2268. .I acme (1).
  2269. .Ex
  2270. acid: pfl(main)
  2271. ls.c:48
  2272. .Ee
  2273. .\"
  2274. .\"
  2275. .\"
  2276. .Ip \f(CW{}\fP procs "" "Print active process list
  2277. .CW procs
  2278. prints a list of active process attached to the debugger. Each process
  2279. produces a single line of output giving the pid, process state, the address
  2280. the process is currently executing, and the
  2281. .CW setproc
  2282. command required to make that process current.
  2283. The current process is marked in the first column with a
  2284. .CW >
  2285. character. The debugger maintains a list of processes in the variable
  2286. .CW proclist .
  2287. .Ex
  2288. acid: procs()
  2289. >62: Stopped at main+0x4 setproc(62)
  2290. 60: Stopped at Binit+0x8 setproc(60)
  2291. .Ee
  2292. .\"
  2293. .\"
  2294. .\"
  2295. .Ip \f(CW{}\fP pstop integer "Print reason process stopped
  2296. .CW pstop
  2297. prints the status of the process specified by the
  2298. .I integer
  2299. pid supplied as its argument.
  2300. .CW pstop
  2301. is usually called from
  2302. .CW stopped
  2303. every time a process enters the
  2304. .CW Stopped
  2305. state.
  2306. .Ex
  2307. acid: pstop(62)
  2308. 0x0000003e: breakpoint main+0x4 MOVW R31,0x0(R29)
  2309. .Ee
  2310. .\"
  2311. .\"
  2312. .\"
  2313. .Ip \f(CW{}\fP regs "" "Print registers
  2314. .CW regs
  2315. prints the contents of both the general and special purpose registers.
  2316. .CW regs
  2317. calls
  2318. .CW spr
  2319. then
  2320. .CW gpr
  2321. to display the contents of the registers.
  2322. .KE
  2323. .\"
  2324. .\"
  2325. .\"
  2326. .Ip \f(CW{}\fP source "" "Summarize source data base
  2327. .CW source
  2328. prints the directory search path followed by a list of currently loaded
  2329. source files. The source management functions
  2330. .CW src
  2331. and
  2332. .CW findsrc
  2333. use the search path to locate and load source files. Source files are
  2334. loaded incrementally into a source data base during debugging. A list
  2335. of loaded files is stored in the variable
  2336. .CW srcfiles
  2337. and the contents of each source file in the variable
  2338. .CW srctext .
  2339. .Ex
  2340. acid: source()
  2341. /n/bootes/sys/src/libbio/
  2342. ./
  2343. /sys/src/libc/port/
  2344. /sys/src/libc/9sys/
  2345. /sys/src/libc/mips/
  2346. binit.c
  2347. .Ee
  2348. .\"
  2349. .\"
  2350. .\"
  2351. .Ip \f(CW{}\fP spr "" "Print special purpose registers
  2352. .CW spr
  2353. prints the contents of the processor control and memory management
  2354. registers. Where possible, the contents of the registers are decoded
  2355. to provide extra information; for example the
  2356. .CW CAUSE
  2357. register on the MIPS is
  2358. printed both in hexadecimal and using the
  2359. .CW reason
  2360. function.
  2361. .Ex
  2362. acid: spr()
  2363. PC 0x00001024 main+0x4 ls.c:48
  2364. SP 0x7fffef68 LINK 0x00006264 _main+0x28 main9.s:12
  2365. STATUS 0x0000ff33 CAUSE 0x00000024 breakpoint
  2366. TLBVIR 0x000000d3 BADVADR 0x00001020
  2367. HI 0x00000004 LO 0x00001ff7
  2368. .Ee
  2369. .\"
  2370. .\"
  2371. .\"
  2372. .Ip \f(CW{}\fP src integer "Print lines of source
  2373. .CW src
  2374. interprets its
  2375. .I integer
  2376. argument as a text address and uses this address to print 5 lines
  2377. of source before and after the address. The current line is marked with a
  2378. .CW >
  2379. character.
  2380. .CW src
  2381. uses the source search path maintained by
  2382. .CW source
  2383. and
  2384. .CW addsrcdir
  2385. to locate the required source files.
  2386. .Ex
  2387. acid: src(*PC)
  2388. ls.c:47
  2389. 42 Biobuf bin;
  2390. 43
  2391. 44 #define HUNK 50
  2392. 45
  2393. 46 void
  2394. >47 main(int argc, char *argv[])
  2395. 48 {
  2396. 49 int i, fd;
  2397. 50 char buf[64];
  2398. 51
  2399. 52 Binit(&bin, 1, OWRITE);
  2400. .Ee
  2401. .\"
  2402. .\"
  2403. .\"
  2404. .Ip \f(CW{}\fP step "" "Single step process
  2405. .CW step
  2406. causes the debugged process to execute a single machine level instruction.
  2407. If the program is stopped on a breakpoint set by
  2408. .CW bpset
  2409. it is first removed, the single step executed, and the breakpoint replaced.
  2410. .CW step
  2411. uses
  2412. .CW follow
  2413. to predict the address of the program counter after the current instruction
  2414. has been executed. A breakpoint is placed at each of these predicted addresses
  2415. and the process is started. When the process stops the breakpoints are removed.
  2416. .Ex
  2417. acid: step()
  2418. 62: breakpoint main+0x8 MOVW R1,argc+4(FP)
  2419. .Ee
  2420. .\"
  2421. .\"
  2422. .\"
  2423. .Ip \f(CW{}\fP stk "" "Stack trace
  2424. .CW stk
  2425. produces a short format stack trace. The stack trace includes each function
  2426. in the stack, where it was called from, and the value of the parameters.
  2427. The short format omits the values of automatic variables.
  2428. Parameters are assumed to be integer values in the format
  2429. .CW X ;
  2430. to print a parameter in the correct format use the
  2431. .CW :
  2432. to obtain its address, apply the correct format, and use the
  2433. .CW *
  2434. indirection operator to find its value.
  2435. It may be necessary to single step a couple of instructions into
  2436. a function to get a correct stack trace because the frame pointer adjustment
  2437. instruction may get scheduled down into the body of the function.
  2438. .Ex
  2439. acid: stk()
  2440. At pc:0x00001028:main+0x8 ls.c:48
  2441. main(argc=0x00000002,argv=0x7fffefe4) ls.c:48
  2442. called from _main+0x20 main9.s:10
  2443. .Ee
  2444. .\"
  2445. .\"
  2446. .\"
  2447. .Ip \f(CW{}\fP stmnt "" "Execute a single statement
  2448. .CW stmnt
  2449. executes a single language level statement.
  2450. .CW stmnt
  2451. displays each machine level instruction as it is executed. When the executed
  2452. statement is completed the source for the next statement is displayed.
  2453. Unlike
  2454. .CW next ,
  2455. the
  2456. .CW stmnt
  2457. function will trace down through function calls.
  2458. .Ex
  2459. acid: stmnt()
  2460. 62: breakpoint main+0x18 MOVW R5,0xc(R29)
  2461. 62: breakpoint main+0x1c JAL Binit(SB)
  2462. 62: breakpoint Binit ADD $-0x18,R29
  2463. binit.c:91
  2464. 89 int
  2465. 90 Binit(Biobuf *bp, int f, int mode)
  2466. >91 {
  2467. .Ee
  2468. .\"
  2469. .\"
  2470. .\"
  2471. .Ip \f(CW{}\fP stopped integer "Report status of stopped process
  2472. .CW stopped
  2473. is called automatically by the interpreter
  2474. every time a process enters the
  2475. .CW Stopped
  2476. state, such as when it hits a breakpoint.
  2477. The pid is passed as the
  2478. .I integer
  2479. argument. The default implementation just calls
  2480. .CW pstop ,
  2481. but the function may be changed to provide more information or perform fine control
  2482. of execution. Note that
  2483. .CW stopped
  2484. should return; for example, calling
  2485. .CW step
  2486. in
  2487. .CW stopped
  2488. will recur until the interpreter runs out of stack space.
  2489. .Ex
  2490. acid: defn stopped(pid) {
  2491. if *lflag != 0 then error("lflag modified");
  2492. }
  2493. acid: progargs = "-l"
  2494. acid: new();
  2495. acid: while 1 do step();
  2496. <stdin>:7: (error) lflag modified
  2497. acid: stk()
  2498. At pc:0x00001220:main+0x200 ls.c:54
  2499. main(argc=0x00000001,argv=0x7fffffe8) ls.c:48
  2500. called from _main+0x20 main9.s:10
  2501. .Ee
  2502. .\"
  2503. .\"
  2504. .\"
  2505. .Ip \f(CW{}\fP symbols string "Search symbol table
  2506. .CW symbols
  2507. uses the regular expression supplied by
  2508. .I string
  2509. to search the symbol table for symbols whose name matches the
  2510. regular expression.
  2511. .Ex
  2512. acid: symbols("main")
  2513. main T 0x00001020
  2514. _main T 0x0000623c
  2515. .Ee
  2516. .\"
  2517. .\"
  2518. .\"
  2519. .Ip \f(CW{}\fP win "" "Start new process in a window
  2520. .CW win
  2521. performs exactly the same function as
  2522. .CW new
  2523. but uses the window system to create a new window for the debugged process.
  2524. The variable
  2525. .CW progargs
  2526. supplies arguments to the new process.
  2527. The environment variable
  2528. .CW $8½srv
  2529. must be set to allow the interpreter to locate the mount channel for the
  2530. window system.
  2531. The window is created in the top left corner of the screen and is
  2532. 400x600 pixels in size. The
  2533. .CW win
  2534. function may be modified to alter the geometry.
  2535. The window system will not be able to deliver notes in the new window
  2536. since the pid of the created process is not passed when the server is
  2537. mounted to create a new window.
  2538. .Ex
  2539. acid: win()
  2540. .Ee