.am DS.ft I...am DE.ft R...ta 1i 2.3i 4.5i  (optional to set tabs).TLAcid Reference Manual.AUPhil Winterbottomphilw@plan9.bell-labs.com.FS\l'1i'.brPreviously appeared with minor differences as the``Acid Manual'' in.I "Plan 9 Programmer's Manual, Volume 2 (Second Edition)"..FE.SHIntroduction.PPAcid is a general purpose, source level symbolic debugger.The debugger is built around a simple command language. The command language, distinct from the language of the program being debugged,provides a flexible user interface that allows the debuggerinterface to be customized for a specific application or architecture.Moreover, it provides an opportunity to write test andverification code independently of a program's source code.Acid is able to debug multipleprocesses provided they share a common set of symbols, such as the processes ina threaded program..PPLike other language-based solutions, Acid presents a poor user interface butprovides a powerful debugging tool.Application of Acid to hard problems is best approached by writing functions off-line(perhaps loading them with the.CW includefunction or using the support provided by.I acme (1)),rather than by trying to type intricate Acid operationsat the interactive prompt..PPAcid allows the execution of a program to be controlled by operating on itsstate while it is stopped and by monitoring and controlling its executionwhen it is running. Each program action that causes a change of execution state is reflected by the executionof an Acid function, which may be user defined.A library of default functions provides the functionality of a normal debugger..PPOn Plan 9, a process is controlled by writing messages to a control file in the.I proc (3)file system. Each control message has a corresponding Acid function, whichsends the message to the process. These functions take a process id.I pid ) (as anargument. The memory and text file of the program may be manipulated usingthe indirection operators. The symbol table, including source cross reference,is available to an Acid program. The combination allows complex operationsto be performed both in terms of control flow and data manipulation..SHInput format and \f(CWwhatis\fP.PPComments start with.CW //and continue to the end of the line.Input is a series of statements and expressions separated by semicolons.At the top level of the interpreter, the builtin function.CW printis called automatically to display the result of all expressions except function calls.A unary.CW +may be used as a shorthand to force the result of a function call to be printed..PPAlso at the top level, newlines are treated as semicolonsby the parser, so semicolons are unnecessary when evaluating expressions..PPWhen Acid starts, it loads the default program modules,enters interactive mode, and prints a prompt. In this state Acid acceptseither function definitions or statements to be evaluated.In this interactive modestatements are evaluated immediately, while function definitions arestored for later invocation..PPThe.CW whatisoperator can be used to report the state of identifiers known to the interpreter.With no argument,.CW whatisreports the name of all defined Acid functions; when supplied with an identifieras an argument it reports any variable, function, or type definitionassociated with the identifier.Because of the way the interpreter handles semicolons,the result of a.CW whatisstatement can be returned directly to Acid without adding semicolons.A syntax error or interrupt returns Acid to the normal evaluationmode; any partially evaluated definitions are lost..SHUsing the Library Functions.PPAfter loading the program binary, Acid loads the portable and architecture-specificlibrary functions  that form the standard debugging environment.These files are Acid source code and are human-readable.The following example uses the standard debugging library to show howlanguage and program interact:.P1% acid /bin/ls/bin/ls:mips plan 9 executable /sys/lib/acid/port/sys/lib/acid/mipsacid: new()75721: system call  _main ADD  $-0x14,R2975721: breakpoint   main+0x4   MOVW  R31,0x0(R29)acid: bpset(ls)acid: cont()75721: breakpoint   ls    ADD  $-0x16c8,R29acid: stk()At pc:0x0000141c:ls /sys/src/cmd/ls.c:87ls(s=0x0000004d,multi=0x00000000) /sys/src/cmd/ls.c:87    called from main+0xf4 /sys/src/cmd/ls.c:79main(argc=0x00000000,argv=0x7ffffff0) /sys/src/cmd/ls.c:48    called from _main+0x20 /sys/src/libc/mips/main9.s:10acid: PC0xc0000f60acid: *PC0x0000141cacid: ls0x0000141c.P2The function.CW new()creates a new process and stops it at the first instruction.This change in state is reported by a call to theAcid function.CW stopped ,which is called by the interpreter whenever the debugged program stops..CW Stoppedprints the status line giving the pid, the reason the program stoppedand the address and instruction at the current PC.The function.CW bpsetmakes an entry in the breakpoint table and plants a breakpoint in memory.The.CW contfunction continues the process, allowing it to run until some conditioncauses it to stop. In this case the program hits the breakpoint placed onthe function.CW lsin the C program. Once again the.CW stoppedroutine is called to print the status of the program. The function.CW stkprints a C stack trace of the current process. It is implemented usinga builtin Acid function that returns the stack trace as a list; the codethat formats the information is all written in Acid. The Acid variable.CW PCholds the address of the cell where the current value of the processor register.CW PCis stored. By indirecting throughthe value of.CW PCthe address where the program is stopped can be found.All of the processor registers are available by the same mechanism..SHTypes.PPAn Acid variable has one of four types:.I integer ,.I float ,.I list ,or.I string .The type of a variable is inferred from the type of the right-handside of the assignment expression which last set its value.Referencing a variable that has not yetbeen assigned draws a "used but not set" error. Many of the operators maybe applied to more thanone type; for these operators the action of the operator is determined bythe types of its operands. The action of each operator is defined in the.I Expressionssection of this manual..SHVariables.PPAcid has three kinds of variables: variables defined by the symbol tableof the debugged program, variables that are defined and maintainedby the interpreter as the debugged program changes state, and variablesdefined and used by Acid programs..PPSome examples of variables maintained by the interpreter are the registerpointers listed by name in the Acid list variable.CW registers ,and the symbol table listed by name and contents in the Acid variable.CW symbols ..PPThe variable.CW pidis updated by the interpreter to select the most recently created processor the process selected by the.CW setprocbuiltin function..SH 1Formats.PPIn addition to a type, variables have formats. The format is a codeletter that determines the printing style and the effect of some of theoperators on that variable. The format codes are derived from the formatletters used by.I db (1).By default, symbol table variables and numeric constantsare assigned the format code.CW X ,which specifies 32-bit hexadecimal.Printing a variable with this code yields the output.CW 0x00123456 .The format code of a variable may be changed from the default by using the builtin function.CW fmt .This function takes two arguments, an expression and a format code. Afterthe expression is evaluated the new format code is attached to the resultand forms the return value from.CW fmt .The backslash operator is a short form of.CW fmt .The format supplied by the backslash operator must be the format characterrather than an expression.If the result is assigned to a variable the new format code is maintainedin the variable. For example:.P1acid: x=10acid: print(x)0x0000000a acid: x = fmt(x, 'D')acid: print(x, fmt(x, 'X'))10 0x0000000aacid: x10acid: x\eo12.P2The supported format characters are:.RS.IP \f(CWo\fPPrint two-byte integer in octal..IP \f(CWO\fPPrint four-byte integer in octal..IP \f(CWq\fPPrint two-byte integer in signed octal..IP \f(CWQ\fPPrint four-byte integer in signed octal..IP \f(CWB\fPPrint four-byte integer in binary..IP \f(CWd\fPPrint two-byte integer in signed decimal..IP \f(CWD\fPPrint four-byte integer in signed decimal..IP \f(CWY\fPPrint eight-byte integer in signed decimal..IP \f(CWx\fPPrint two-byte integer in hexadecimal..IP \f(CWX\fPPrint four-byte integer in hexadecimal..IP \f(CWu\fPPrint two-byte integer in unsigned decimal..IP \f(CWU\fPPrint four-byte integer in unsigned decimal..IP \f(CWZ\fPPrint eight-byte integer in unsigned decimal..IP \f(CWf\fPPrint single-precision floating point number..IP \f(CWF\fPPrint double-precision floating point number..IP \f(CWg\fPPrint a single precision floating point number in string format..IP \f(CWG\fPPrint a double precision floating point number in string format..IP \f(CWb\fPPrint byte in hexadecimal..IP \f(CWc\fPPrint byte as an ASCII character..IP \f(CWC\fPLike.CW c ,withprintable ASCII characters represented normally andothers printed in the form \f(CW\ex\fInn\fR..IP \f(CWs\fPInterpret the addressed bytes as UTF charactersand print successive characters until a zero byte is reached..IP \f(CWr\fPPrint a two-byte integer as a rune..IP \f(CWR\fPPrint successive two-byte integers as runesuntil a zero rune is reached..IP \f(CWY\fPPrint successive eight-byte integers in hexadecimal..IP \f(CWi\fPPrint as machine instructions..IP \f(CWI\fPAs.CW iabove, but print the machine instructions inan alternate form if possible:.CW sunsparcand.CW mipscoreproduce the manufacturers' syntax..IP \f(CWa\fPPrint the value in symbolic form..RE.SHComplex types.PPAcid permits the definition of the layout of memory.The usual method is to use the.CW -aflag of the compilers to produce Acid-language descriptions of data structures (see.I 2c (1))although such definitions can be typed interactively.The keywords.CW complex ,.CW adt ,.CW aggr ,and.CW unionare all equivalent; the compiler uses the synonyms to document the declarations.A complex type is described as a set of members, each containing a format letter,an offset in the structure, and a name.  For example, the C structure.P1struct List {	int         type;	struct List *next;};.P2is described by the Acid statement.P1complex List {	'D'	0	type;	'X'	4	next;};.P2.SHScope.PPVariables are global unless they are either parameters to functionsor are declared as.CW localin a function body. Parameters and local variables are available only inthe body of the function in which they are instantiated.Variables are dynamically bound: if a function declares a local variablewith the same name as a global variable, the global variable will be hiddenwhenever the function is executing.For example, if a function.CW fhas a local called.CW main ,any function called below.CW fwill see the local version of.CW main ,not the external symbol..SH 1Addressing.PPSince the symbol table specifies addresses,to access the value of program variablesan extra level of indirectionis required relative to the source code.For consistency, the registers are maintained as pointers as well; Acid variables with the namesof processor registers point to cells holding the saved registers..PPThe location in a file or memory image associated withan address is calculated from a mapassociated with the file.Each map contains one or more quadruples (\c.I t ,.I b ,.I e ,.I f \|),defining a segment named.I t(usually .CW text ,.CW data ,.CW regs ,or.CW fpregs )mapping addresses in the range.I bthrough.I eto the part of the filebeginning atoffset.I f .The memory model of a Plan 9 process assumesthat segments are disjoint.  Therecan be more than one segment of a given type (e.g., a processmay have more than one text segment) but segmentsmay not overlap.An address.I ais translatedto a file addressby finding a segmentfor which.I b+.I a<.I e ;the location in the fileis then.I address+.I f\-.I b ..PPUsually,the text and initialized data of a programare mapped by segments called .CW textand.CW data .Since a program file does not contain bss, stack, or register data,these data arenot mapped by the data segment.The text segment is mapped similarly in the memory image ofa normal (i.e., non-kernel) process.However, the segment called .CW *datamaps memory from the beginning to the end of the program's data space.This region contains the program's static data, the bss, theheap and the stack.  A segmentcalled.CW *regsmaps the registers;.CW *fpregsmaps the floating point registers (if they exist)..PPSometimes it is useful to define a map with a single segmentmapping the region from 0 to 0xFFFFFFFF; such a mapallows the entire file to be examinedwithout address translation.  The builtin function.CW mapexamines and modifies Acid's map for a process..SH 1Name Conflicts.PPName conflicts between keywords in the Acid language, symbols in the program,and previously defined functions are resolved when the interpreter starts up.Each name is made unique by prefixing enough.CW $characters to the front of the name to make it unique. Acid reportsa list of each name change at startup. The report looks like this:.P1/bin/sam: mips plan 9 executable/lib/acid/port/lib/acid/mipsSymbol renames:	append=$append T/0xa4e40acid:.P2The symbol.CW appendis both a keyword and a text symbol in the program. The message reportsthat the text symbol is now named.CW $append ..SHExpressions.PPOperators have the samebinding and precedence as in C.For operators of equal precedence, expressions are evaluated from left to right. .SH 1Boolean expressions.PPIf an expression is evaluated for a boolean condition the testperformed depends on the type of the result. If the result is of.I integeror.I floatingtype the result is true if the value is non-zero. If the expression is a.I listthe result is true if there are any members in the list.If the expression is a.I stringthe result is true if there are any characters in the string..DS	primary-expression:		identifier		identifier \f(CW:\fP identifier		constant		\f(CW(\fP expression \f(CW)\fP		\f(CW{\fP elist \f(CW}\fP

Lines 1–500 of 2519. Load more