Subversion Repositories planix.SVN

.HTML "Acid Manual

.am DS

.ft I

..

.ta 1i 2.3i 4.5i  (optional to set tabs)

.TL

Acid Manual

.AU

Phil Winterbottom

philw@plan9.bell-labs.com

.SH

Introduction

.PP

Acid 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 debugger

interface to be customized for a specific application or architecture.

Moreover, it provides an opportunity to write test and

verification code independently of a program's source code.

Acid is able to debug multiple

processes provided they share a common set of symbols, such as the processes in

a threaded program.

.PP

Like other language-based solutions, Acid presents a poor user interface but

provides a powerful debugging tool.

Application of Acid to hard problems is best approached by writing functions off-line

(perhaps loading them with the

.CW include

function or using the support provided by

.I acme (1)),

rather than by trying to type intricate Acid operations

at the interactive prompt.

.PP

Acid allows the execution of a program to be controlled by operating on its

state while it is stopped and by monitoring and controlling its execution

when it is running. Each program action that causes a change 

of execution state is reflected by the execution

of an Acid function, which may be user defined.

A library of default functions provides the functionality of a normal debugger.

.PP

A Plan 9 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, which

sends the message to the process. These functions take a process id

.I pid ) (

as an

argument. The memory and text file of the program may be manipulated using

the indirection operators. The symbol table, including source cross reference,

is available to an Acid program. The combination allows complex operations

to be performed both in terms of control flow and data manipulation.

.SH

Input format and \f(CWwhatis\fP

.PP

Comments 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 print

is 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.

.PP

Also at the top level, newlines are treated as semicolons

by the parser, so semicolons are unnecessary when evaluating expressions.

.PP

When Acid starts, it loads the default program modules,

enters interactive mode, and prints a prompt. In this state Acid accepts

either function definitions or statements to be evaluated.

In this interactive mode

statements are evaluated immediately, while function definitions are

stored for later invocation.

.PP

The

.CW whatis

operator can be used to report the state of identifiers known to the interpreter.

With no argument,

.CW whatis

reports the name of all defined Acid functions; when supplied with an identifier

as an argument it reports any variable, function, or type definition

associated with the identifier.

Because of the way the interpreter handles semicolons,

the result of a

.CW whatis

statement can be returned directly to Acid without adding semicolons.

A syntax error or interrupt returns Acid to the normal evaluation

mode; any partially evaluated definitions are lost.

.SH

Using the Library Functions

.PP

After loading the program binary, Acid loads the portable and architecture-specific

library 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 how

language and program interact:

.P1

% acid /bin/ls

/bin/ls:mips plan 9 executable

/sys/lib/acid/port

/sys/lib/acid/mips

acid: new()

75721: system call  _main ADD  $-0x14,R29

75721: breakpoint   main+0x4   MOVW  R31,0x0(R29)

acid: bpset(ls)

acid: cont()

75721: breakpoint   ls    ADD  $-0x16c8,R29

acid: stk()

At pc:0x0000141c:ls /sys/src/cmd/ls.c:87

ls(s=0x0000004d,multi=0x00000000) /sys/src/cmd/ls.c:87

    called from main+0xf4 /sys/src/cmd/ls.c:79

main(argc=0x00000000,argv=0x7ffffff0) /sys/src/cmd/ls.c:48

    called from _main+0x20 /sys/src/libc/mips/main9.s:10

acid: PC

0xc0000f60

acid: *PC

0x0000141c

acid: ls

0x0000141c

.P2

The function

.CW new()

creates a new process and stops it at the first instruction.

This change in state is reported by a call to the

Acid function

.CW stopped ,

which is called by the interpreter whenever the debugged program stops.

.CW Stopped

prints the status line giving the pid, the reason the program stopped

and the address and instruction at the current PC.

The function

.CW bpset

makes an entry in the breakpoint table and plants a breakpoint in memory.

The

.CW cont

function continues the process, allowing it to run until some condition

causes it to stop. In this case the program hits the breakpoint placed on

the function

.CW ls

in the C program. Once again the

.CW stopped

routine is called to print the status of the program. The function

.CW stk

prints a C stack trace of the current process. It is implemented using

a builtin Acid function that returns the stack trace as a list; the code

that formats the information is all written in Acid. 

The Acid variable

.CW PC

holds the address of the 

cell where the current value of the processor register

.CW PC

is stored. By indirecting through

the value of

.CW PC

the address where the program is stopped can be found.

All of the processor registers are available by the same mechanism.

.SH

Types

.PP

An 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-hand

side of the assignment expression which last set its value.

Referencing a variable that has not yet

been assigned draws a "used but not set" error. Many of the operators may

be applied to more than

one type; for these operators the action of the operator is determined by

the types of its operands. The action of each operator is defined in the

.I Expressions

section of this manual.

.SH

Variables

.PP

Acid has three kinds of variables: variables defined by the symbol table

of the debugged program, variables that are defined and maintained

by the interpreter as the debugged program changes state, and variables

defined and used by Acid programs.

.PP

Some examples of variables maintained by the interpreter are the register

pointers 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 .

.PP

The variable

.CW pid

is updated by the interpreter to select the most recently created process

or the process selected by the

.CW setproc

builtin function.

.SH 1

Formats

.PP

In addition to a type, variables have formats. The format is a code

letter that determines the printing style and the effect of some of the

operators on that variable. The format codes are derived from the format

letters used by

.I db (1).

By default, symbol table variables and numeric constants

are 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. After

the expression is evaluated the new format code is attached to the result

and 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 character

rather than an expression.

If the result is assigned to a variable the new format code is maintained

in the variable. For example:

.P1

acid: x=10

acid: print(x)

0x0000000a 

acid: x = fmt(x, 'D')

acid: print(x, fmt(x, 'X'))

10 0x0000000a

acid: x

10

acid: x\eo

12

.P2

The supported format characters are:

.RS

.IP \f(CWo\fP

Print two-byte integer in octal.

.IP \f(CWO\fP

Print four-byte integer in octal.

.IP \f(CWq\fP

Print two-byte integer in signed octal.

.IP \f(CWQ\fP

Print four-byte integer in signed octal.

.IP \f(CWB\fP

Print four-byte integer in binary.

.IP \f(CWd\fP

Print two-byte integer in signed decimal.

.IP \f(CWD\fP

Print four-byte integer in signed decimal.

.IP \f(CWV\fP

Print eight-byte integer in signed decimal.

.IP \f(CWZ\fP

Print eight-byte integer in unsigned decimal.

.IP \f(CWx\fP

Print two-byte integer in hexadecimal.

.IP \f(CWX\fP

Print four-byte integer in hexadecimal.

.IP \f(CWY\fP

Print eight-byte integer in hexadecimal.

.IP \f(CWu\fP

Print two-byte integer in unsigned decimal.

.IP \f(CWU\fP

Print four-byte integer in unsigned decimal.

.IP \f(CWf\fP

Print single-precision floating point number.

.IP \f(CWF\fP

Print double-precision floating point number.

.IP \f(CWg\fP

Print a single precision floating point number in string format.

.IP \f(CWG\fP

Print a double precision floating point number in string format.

.IP \f(CWb\fP

Print byte in hexadecimal.

.IP \f(CWc\fP

Print byte as an ASCII character.

.IP \f(CWC\fP

Like

.CW c ,

with

printable ASCII characters represented normally and

others printed in the form \f(CW\ex\fInn\fR.

.IP \f(CWs\fP

Interpret the addressed bytes as UTF characters

and print successive characters until a zero byte is reached.

.IP \f(CWr\fP

Print a two-byte integer as a rune.

.IP \f(CWR\fP

Print successive two-byte integers as runes

until a zero rune is reached.

.IP \f(CWi\fP

Print as machine instructions.

.IP \f(CWI\fP

As

.CW i

above, but print the machine instructions in

an alternate form if possible:

.CW sunsparc

and

.CW mipsco

reproduce the manufacturers' syntax.

.IP \f(CWa\fP

Print the value in symbolic form.

.RE

.SH

Complex types

.PP

Acid permits the definition of the layout of memory.

The usual method is to use the

.CW -a

flag 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 union

are 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

.P1

struct List {

	int         type;

	struct List *next;

};

.P2

is described by the Acid statement

.P1

complex List {

	'D'	0	type;

	'X'	4	next;

};

.P2

.SH

Scope

.PP

Variables are global unless they are either parameters to functions

or are declared as

.CW local

in a function body. Parameters and local variables are available only in

the body of the function in which they are instantiated.

Variables are dynamically bound: if a function declares a local variable

with the same name as a global variable, the global variable will be hidden

whenever the function is executing.

For example, if a function

.CW f

has a local called

.CW main ,

any function called below

.CW f

will see the local version of

.CW main ,

not the external symbol.

.SH 1

Addressing

.PP

Since the symbol table specifies addresses,

to access the value of program variables

an extra level of indirection

is required relative to the source code.

For consistency, the registers are maintained as pointers as well; Acid variables with the names

of processor registers point to cells holding the saved registers.

.PP

The location in a file or memory image associated with

an address is calculated from a map

associated 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 b

through

.I e

to the part of the file

beginning at

offset

.I f .

The memory model of a Plan 9 process assumes

that segments are disjoint.  There

can be more than one segment of a given type (e.g., a process

may have more than one text segment) but segments

may not overlap.

An address

.I a

is translated

to a file address

by finding a segment

for which

.I b

+

.I a

<

.I e ;

the location in the file

is then

.I address

+

.I f

\-

.I b .

.PP

Usually,

the text and initialized data of a program

are mapped by segments called 

.CW text

and

.CW data .

Since a program file does not contain bss, stack, or register data,

these data are

not mapped by the data segment.

The text segment is mapped similarly in the memory image of

a normal (i.e., non-kernel) process.

However, the segment called 

.CW *data

maps memory from the beginning to the end of the program's data space.

This region contains the program's static data, the bss, the

heap and the stack.  A segment

called

.CW *regs

maps the registers;

.CW *fpregs

maps the floating point registers.

.PP

Sometimes it is useful to define a map with a single segment

mapping the region from 0 to 0xFFFFFFFF; such a map

allows the entire file to be examined

without address translation.  The builtin function

.CW map

examines and modifies Acid's map for a process.

.SH 1

Name Conflicts

.PP

Name 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 reports

a list of each name change at startup. The report looks like this:

.P1

/bin/sam: mips plan 9 executable

/lib/acid/port

/lib/acid/mips

Symbol renames:

	append=$append T/0xa4e40

acid:

.P2

The symbol

.CW append

is both a keyword and a text symbol in the program. The message reports

that the text symbol is now named

.CW $append .

.SH

Expressions

.PP

Operators have the same

binding and precedence as in C.

For operators of equal precedence, expressions are evaluated from left to right. 

.SH 1

Boolean expressions

.PP

If an expression is evaluated for a boolean condition the test

performed depends on the type of the result. If the result is of

.I integer

or

.I floating

type the result is true if the value is non-zero. If the expression is a

.I list

the result is true if there are any members in the list.

If the expression is a

.I string

the 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

	elist:

		expression

		elist , expression

.DE

An identifier may be any legal Acid variable. The colon operator returns the

address of parameters or local variables in the current stack of a program.

For example:

.P1

*main:argc

.P2

prints the number of arguments passed into main. Local variables and parameters

can only be referenced after the frame has been established. It may be necessary to

step a program over the first few instructions of a breakpointed function to properly set

the frame.

.PP

Constants follow the same lexical rules as C.

A list of expressions delimited by braces forms a list constructor.

A new list is produced by evaluating each expression when the constructor is executed.

The empty list is formed from

.CW {} .

.P1

acid: x = 10

acid: l = { 1, x, 2\eD }

acid: x = 20

acid: l

{0x00000001 , 0x0000000a , 2 }

.P2

.SH 1

Lists

.PP

Several operators manipulate lists.

.DS

	list-expression:

		primary-expression

		\f(CWhead\fP primary-expression

		\f(CWtail\fP primary-expression

		\f(CWappend\fP expression \f(CW,\fP primary-expression

		\f(CWdelete\fP expression \f(CW,\fP primary-expression

.DE

The

.I primary-expression

for

.CW head

and

.CW tail

must yield a value of type

.I list .

If there are no elements in the list the value of

.CW head

or

.CW tail

will be the empty list. Otherwise

.CW head

evaluates to the first element of the list and

.CW tail

evaluates to the rest.

.P1

acid: head {}

{}

acid: head {1, 2, 3, 4}

0x00000001 

acid: tail {1, 2, 3, 4}

{0x00000002 , 0x00000003 , 0x00000004 }

.P2

The first operand of

.CW append 

and

.CW delete

must be an expression that yields a

.I list .

.CW Append

places the result of evaluating

.I primary-expression

at the end of the list.

The

.I primary-expression

supplied to

.CW delete

must evaluate to an integer;

.CW delete

removes the 

.I n 'th

item from the list, where

.I n

is integral value of

.I primary-expression.

List indices are zero-based.

.P1

	acid: append {1, 2}, 3

	{0x00000001 , 0x00000002 , 0x00000003 }

	acid: delete {1, 2, 3}, 1

	{0x00000001 , 0x00000003 }

.P2

.PP

Assigning a list to a variable copies a reference to the list; if a list variable

is copied it still points at the same list.  To copy a list, the elements must

be copied piecewise using

.CW head

and

.CW append .

.SH 1

Operators

.PP

.DS

	postfix-expression:

		list-expression

		postfix-expression \f(CW[\fP expression \f(CW]\fP

		postfix-expression \f(CW(\fP argument-list \f(CW)\fP

		postfix-expression \f(CW.\fP tag

		postfix-expression \f(CW->\fP tag 

		postfix-expression \f(CW++\fP

		postfix-expression \f(CW--\fP

	argument-list:

		expression

		argument-list , expression

.DE

The

.CW [

.I expression

.CW ]

operator performs indexing.

The indexing expression must result in an expression of

.I integer

type, say

.I n .

The operation depends on the type of

.I postfix-expression .

If the

.I postfix-expression

yields an

.I integer

it is assumed to be the base address of an array in the memory image.

The index offsets into this array; the size of the array members is

determined by the format associated with the

.I postfix-expression .

If the 

.I postfix-expression

yields a

.I string

the index operator fetches the

.I n 'th

character

of the string. If the index points beyond the end

of the string, a zero is returned.

If the

.I postfix-expression

yields a

.I list

then the indexing operation returns the

.I n 'th

item of the list.

If the list contains less than

.I n

items the empty list

.CW {}

is returned.

.PP

The

.CW ++

and

.CW --

operators increment and decrement integer variables.

The amount of increment or decrement depends on the format code. These postfix

operators return the value of the variable before the increment or decrement

has taken place.

.DS

	unary-expression:

		postfix-expression

		\f(CW++\fP unary-expression

		\f(CW--\fP unary-expression

	unary-operator: one of

		\f(CW*\fP \f(CW@\fP \f(CW+\fP \f(CW-\fP ~ \f(CW!\fP

.DE

The operators

.CW *

and

.CW @

are the indirection operators.

.CW @

references a value from the text file of the program being debugged.

The size of the value depends on the format code. The

.CW *

operator fetches a value from the memory image of a process. If either

operator appears on the left-hand side of an assignment statement, either the file

or memory will be written. The file can only be modified when Acid is invoked

with the

.CW -w

option.

The prefix

.CW ++

and

.CW --

operators perform the same operation as their postfix counterparts but

return the value after the increment or decrement has been performed. Since the

.CW ++

and

.CW *

operators fetch and increment the correct amount for the specified format,

the following function prints correct machine instructions on a machine with

variable length instructions, such as the 68020 or 386:

.P1

	defn asm(addr)

	{

		addr = fmt(addr, 'i');

		loop 1, 10 do

			print(*addr++, "\en");

	}

.P2

The operators

.CW ~

and

.CW !

perform bitwise and logical negation respectively. Their operands must be of

.I integer

type.

.DS

	cast-expression:

		unary-expression

		unary-expression \f(CW\e\fP format-char

		\f(CW(\fP complex-name \f(CW)\fP unary-expression		

.DE

A unary expression may be preceded by a cast. The cast has the effect of

associating the value of 

.I unary-expression

with a complex type structure.

The result may then be dereferenced using the

.CW .

and

.CW ->

operators.

.PP

An Acid variable may be associated with a complex type

to enable accessing the type's members:

.P1

acid: complex List {

	'D'	0	type;

	'X'	4	next;

};

acid: complex List lhead

acid: lhead.type

10

acid: lhead = ((List)lhead).next

acid: lhead.type

-46

.P2

Note that the

.CW next

field cannot be given a complex type automatically.

.PP

When entered at the top level of the interpreter,

an expression of complex type

is treated specially.

If the type is called

.CW T

and an Acid function also called

.CW T

exists,

then that function will be called with the expression as its argument.

The compiler options

.CW -a

and

.CW -aa

will generate Acid source code defining such complex types and functions; see

.I 2c (1).

.PP

A

.I unary-expression

may be qualified with a format specifier using the

.CW \e

operator. This has the same effect as passing the expression to the

.CW fmt

builtin function.

.DS

	multiplicative-expression:

		cast-expression

		multiplicative-expression \f(CW*\fP multiplicative-expression

		multiplicative-expression \f(CW/\fP multiplicative-expression

		multiplicative-expression \f(CW%\fP multiplicative-expression

.DE

These operate on

.I integer

and 

.I float

types and perform the expected operations:

.CW *

multiplication,

.CW /

division,

.CW %

modulus.

.DS

	additive-expression:

		multiplicative-expression

		additive-expression \f(CW+\fP multiplicative-expression

		additive-expression \f(CW-\fP multiplicative-expression

.DE

These operators perform as expected for

.I integer

and 

.I float

operands.

Unlike in C,

.CW +

and

.CW -

do not scale the addition based on the format of the expression.

This means that

.CW i=i+1

will always add 1 but

.CW i++

will add the size corresponding to the format stored with

.CW i .

If both operands are of either

.I string

or

.I list

type then addition is defined as concatenation. 

Adding a string and an integer is treated as concatenation

with the Unicode character corresponding to the integer.

Subtraction is undefined for strings and lists.

.DS

	shift-expression:

		additive-expression

		shift-expression \f(CW<<\fP additive-expression

		shift-expression \f(CW>>\fP additive-expression

.DE

The

.CW >>

and

.CW <<

operators perform bitwise right and left shifts respectively. Both

require operands of

.I integer

type.

.DS

	relational-expression:

		relational-expression \f(CW<\fP shift-expression

		relational-expression \f(CW>\fP shift-expression

		relational-expression \f(CW<=\fP shift-expression

		relational-expression \f(CW>=\fP shift-expression

	equality-expression:

		relational-expression

		relational-expression \f(CW==\fP equality-expression

		relational-expression \f(CW!=\fP equality-expression

.DE

The comparison operators are

.CW <

(less than),

.CW >

(greater than),

.CW <=

(less than or equal to),

.CW >=

(greater than or equal to),

.CW ==

(equal to) and

.CW !=

(not equal to). The result of a comparison is 0

if the condition is false, otherwise 1. The relational operators can only be

applied to operands of

.I integer

and

.I float

type. The equality operators apply to all types.  Comparing mixed types is legal.

Mixed integer and float compare on the integral value.  Other mixtures are always unequal.

Two lists are equal if they

have the same number of members and a pairwise comparison of the members results

in equality.

.DS

	AND-expression:

		equality-expression

		AND-expression \f(CW&\fP equality-expression

	XOR-expression:

		AND-expression

		XOR-expression \f(CW^\fP AND-expression

	OR-expression:

		XOR-expression

		OR-expression \f(CW|\fP XOR-expression

.DE

These operators perform bitwise logical operations and apply only to the

.I integer

type.

The operators are

.CW &

(logical and),

.CW ^

(exclusive or) and

.CW |

(inclusive or).

.DS

	logical-AND-expression:

		OR-expression

		logical-AND-expression \f(CW&&\fP OR-expression

	logical-OR-expression:

		logical-AND-expression

		logical-OR-expression \f(CW||\fP logical-AND-expression

.DE

The

.CW &&

operator returns 1 if both of its operands evaluate to boolean true, otherwise 0.

The

.CW ||

operator returns 1 if either of its operands evaluates to boolean true,

otherwise 0.

.SH

Statements

.PP

.DS

	\f(CWif\fP expression \f(CWthen\fP statement \f(CWelse\fP statement

	\f(CWif\fP expression \f(CWthen\fP statement

.DE

The

.I expression

is evaluated as a boolean. If its value is true the statement after

the

.CW then

is executed, otherwise the statement after the

.CW else

is executed. The 

.CW else

portion may be omitted.

.DS

	\f(CWwhile\fP expression \f(CWdo\fP statement

.DE

In a while loop, the

.I statement

is executed while the boolean

.I expression

evaluates

true.

.DS

	\f(CWloop\fP startexpr, endexpr \f(CWdo\fP statement

.DE

The two expressions

.I startexpr

and

.I endexpr

are evaluated prior to loop entry.

.I Statement

is evaluated while the value of

.I startexpr

is less than or equal to

.I endexpr .

Both expressions must yield

.I integer

values. The value of

.I startexpr

is

incremented by one for each loop iteration.

Note that there is no explicit loop variable; the

.I expressions

are just values.

.DS

	\f(CWreturn\fP expression

.DE

.CW return

terminates execution of the current function and returns to its caller.

The value of the function is given by expression. Since

.CW return

requires an argument, nil-valued functions should return the empty list

.CW {} .

.DS

	\f(CWlocal\fP variable

.DE

The

.CW local

statement creates a local instance of

.I variable ,

which exists for the duration

of the instance of the function in which it is declared. Binding is dynamic: the local variable,

rather than the previous value of

.I variable ,

is visible to called functions.

After a return from the current function the previous value of

.I variable

is

restored.

.PP

If Acid is interrupted, the values of all local variables are lost,

as if the function returned.

.DS

	\f(CWdefn\fP function-name \f(CW(\fP parameter-list \f(CW)\fP body

	parameter-list:

		variable

		parameter-list , variable

	body:

		\f(CW{\fP statement \f(CW}\fP

.DE

Functions are introduced by the