\section{SOTEST Structure} SOTEST consists of three major pieces: \begin{itemize} \item 80186 (or 80188) engine \item SOTL (thread language) interpreter \item Command-line interface \end{itemize} The first piece, the 80186/8 engine, is capable of simulating one or more 80186/8-based ``machines.'' Each machine is represented by an array of memory, an array of ports, registers, flags, a clock, an interrupt controller, a timer manager, and a DMA controller. The chip select unit is not simulated, but there are other ways to achieve its effects. The engine simulates at the instruction level rather than at the logic level; that is, no 80186 pins are simulated and no logic-level signals are generated. The second piece is the SOTL interpreter. SOTL is the name of the debugging command language, a multi-threaded procedural language that can be used to write test scripts, simulate external hardware, monitor the execution of the target, or perform frequently-used combinations of top-level commands. SOTL supports all of the standard C operators, has procedures and local variables (distinct from the target's procedures and local variables), provides operators to examine and control the simulated 80186, provides access to the target's debugging information (target local variables and type information), and provides access to certain UNIX system calls (in particular, interprocess communication via System V \(msg___\) calls or Berkeley sockets). In addition, threads can send messages to one another. The third piece is the command-line interpreter. It is very simple; it reads a SOTL statement from standard input, creates a thread for it, and starts that thread running. When that thread completes, the user is prompted for another command. \section{Threads and Scheduling} When the user types a command, a thread is created for it. This thread is the ``foreground thread,'' and until it dies, the user cannot execute any more commands. There may only be one foreground thread at a time, but the foreground thread can fork (create) other threads. The user may kill the foreground thread by pressing control-C. Certain commands can cause the foreground thread (or any other thread) to block. Blocking means the thread says it has nothing more to do, for the time being at least. Receiving an event is the only thing that causes a thread to unblock. Before a thread blocks, it specifies which events it's interested in; a read from a certain range of memory addresses, for example, can cause an event. There are several other ways events can be generated, which will be discussed later. The user may also subscribe to events; when the user receives an event, the event is displayed on the screen, and the foreground thread is killed. When the foreground thread dies, either by exiting, when the user receives an event, or when the user presses control-C, all other threads (background threads, which may have been forked from the foreground thread) are then allowed to run until they block or exit. Finally, the user is allowed to type another command, starting a new foreground thread. If a background thread is misbehaving, and simply runs continuously, there is no way for the user to stop it. However, a thread can be put into debug mode. When the user presses control-C, all threads in debug mode are frozen, and the user may type commands. The threads are unfrozen either explicitly by the user (using the \(threadunfreeze\) command), when they are taken out of debug mode, or when the user uses the \(go\) command. When the foreground thread is blocked, and all other threads are blocked or frozen, the engine starts interpreting machine instructions until an event is generated or the user presses control-C. When the machine generates an event for a thread, if the thread is not frozen, it will receive the event and unblock. If the thread is frozen, the event is entered onto an event queue for the thread, which will be processed when the thread is unfrozen. If the thread is in debug mode, a warning message is printed informing the user about the event. Runnable threads have highest priority in the system. As long as any thread has something to do ({\it i.e.,} it is neither blocked nor frozen), it runs, and all machines are effectively halted; registers and the clock hold their values. Further, user input is ignored. However, the user can always take control by pressing control-C. This interrupts whatever SOTEST is doing (executing 80186 instructions or running threads), kills the foreground thread, and marks threads in debug mode (whether blocked or running) as frozen. All threads have the same priority; if several become runnable at once (through being unfrozen or receiving events), which runs first is apparently random. \section{SOTL Types} \subsection{Primitive Types} There are many primitive data types in SOTL. The simplest is the dword, which is an unsigned number from 0 to $2^{32} - 1$. A dword constant is like an integer constant in C, except that Intel hexadecimal notation is permitted ({\it e.g.,} \(0d73h\)). Time is a primitive type, measured in {\it ticks} (clock cycles). A time value is created with the syntax {\it minutes\(:\)seconds\(.\)ticks,} where {\it minutes, seconds,} and {\it ticks} are integer constants. For example, \(1:23.13000000\) represents one minute, 23 seconds, and 13 million ticks. The string is a primitive type; like in C, a string constant is an array of characters in double-quotes, {\it e.g.,} \("hello"\). Unlike in C, strings are not null-terminated; their length is recorded, and they may contain any characters. Strings can also be constructed from hex by using backquotes as in \(`1A2B3C4D`\), in which whitespace is allowed. The string constant \(`41 42 43`\) creates the string \("ABC"\). Strings can be accessed with array reference operators; \("ABC"[1]\) returns 66 (the ASCII code for \(B\)). There is also a primitive type that represents a block of target memory. This type is called a ``block,'' and is created with the syntax {\it \([\)address\(,\)size\(]\).} If the size is 1, 2, or 4, then the block can be used anywhere a dword can be used; when the dword is needed, memory at the address is read (generating memory read events.) The \(memoryfetch\) command creates a string whose characters are the contents of the block. Blocks can also be displayed conveniently with the \(print\) command. For example, \(x=[1234h:5678h,4]\) assigns to x a reference to 4 bytes at address \(1234h:5678\). Then \(x+10\) reads a dword from that address and adds 10 to it, \(print %b x\) prints out the 4 bytes stored there, and \(y=memoryfetch x\) creates a string of length four containing those bytes and assigns it to \(y\). The pattern (or regular expression) is a primitive type. Strings can be tested to see if they can be see if they match a pattern; a pattern matches a set of strings. For example, you can write a pattern to match all strings that start with \(`03 04 05`\) and end with \(`A6`\); see the \(=~\) and \(!~\) operators. The syntax for constructing patterns is described below. Other primitive types include source code modules, machines (processors being simulated), user-defined procedures (called SOTL functions), and references and pointers to target data objects (using target debugging information). UNIX file descriptors and message queue ID's are also primitive types. One final type is the null type; the only null value is \(nil\), which is returned by commands that have no meaningful return value. It is also placed anywhere that would be uninitialized in C (such as in otherwise uninitialized arrays). \subsection{Aggregate Types} The array is the only aggregate type. The lower index of an array is always zero. Arrays grow on demand; accessing an element past the end of an array causes the array to grow. The untouched elements of the array are all initially \(nil\). The elements of an array may be of any type; they need not be all the same type. Although multidimensional arrays are not directly supported, elements of arrays may be other arrays. However, if you set up a cyclical structure (for example, with \(x[0] = 0; x[2] = x;\)) then SOTL's memory manager will never free the array(s) involved in the cycle. Arrays need not be declared. If, before storing anything into a variable, you use the array reference operator on it, the variable becomes an array. Example: \(a[10] = 17; a[13][4] = 26; print a[3]; ==> nil\) \subsection{Booleans} SOTL does not have a boolean type. Similar to C, any non-zero dword is considered true, and 0 is considered false. A string of positive length is considered true, and the empty string is considered false. All values of other types are considered true besides \(nil\), which is considered false. \section{SOTL Identifiers} Identifiers are like C identifiers, except that dollar-sign (\($\)) is allowed within identifiers. It is recommended that you use a dollar-sign as the first character of all SOTL variables, in order to avoid accidental naming conflicts with target symbols. The rules SOTL uses to find the values of identifiers are not simple. This is because SOTL has three namespaces, all of which are in effect simultaneously. There are SOTL variables and objects (global and local), debugging symbols (global and local), and public symbols and segment names. The procedure SOTL follows when looking up an identifier follows. First, locals for the current SOTL function are checked, and SOTL globals are checked. Then, debugging symbols for the current frame are searched. These are the only three context-dependent cases. There is a cache mapping identifiers to their context-independent values; this cache is checked next. If there is nothing in the cache, then the following lists are checked; if anything is found, it is stored in the cache. These lists, in order, are SOTL globals, user-supplied SOTL extension function names, machine names, account names, register names, public symbols, debugging globals (including module-global static variables), and segment names. If an identifier is not found, and it is assigned to, then a SOTL variable is created. If the SOTL code is executing inside a SOTL function, the variable will be created locally to that function; otherwise, it is created globally. If you want to create a SOTL variable explicitly, you can use the \(local\) or \(global\) command operators. It is recommended that you always use these operators when creating variables. Here is an example of what can go wrong if you don't: \code def $foo ($x) { $temp = $x; if ($x > 0) { foo ($x - 1); } print $temp; } $foo(2); \yields(0 1 2) $temp = 10; $foo(2); \yields(0 0 0) \code Notice that the assignment to \($temp\) on line 7 made \($temp\) global, causing the recursive \($foo\) to do something very different than intended. The problem is fixed by inserting \(local $temp;\) after the first line. \section{SOTL Patterns} Patterns are always found between pairs of forward-slashes (\(/\)). Inside the slashes, period (\(.\)) matches any byte, and dollar-sign (\($\)) matches the end of the string. Other elements may be string constants or SOTL variables that hold strings. So, for example, \def\regexpexample{\(\catcode`\&=4\relax\doreexample} \def\doreexample#1\crcr{\halign{\hskip 1in ##\quad\hfil&\rm ##\hfil\cr #1\crcr}\)} \regexpexample `001122` =~ /`00 11 22`/&returns true,\cr `001122` =~ /. `1122` \$/&returns true,\cr `001122` =~ /`0011`/&returns true,\cr `001122` =~ /`0011` \$/&returns false, and\cr `001122` =~ /. . . ./&returns false.\crcr Operators within regular expressions include question-mark (\(?\)), which makes the preceeding term optional; star (\(*\)), which allows the proceeding term to match 0 or more times; plus (\(+\)), which allows the proceeding term to match 1 or more times; and vertical-bar (\(|\)), which matches if either the term on its left or the term on its right matches. Parentheses (\((\) and \()\)) group terms together. Finally, a string in brackets (\([\) and \(]\)) matches any single character which is in the string; if the string is prefixed with caret (\(^\)), it matches any single character not in the string. Thus, \regexpexample `00112233` =~ / (.*) `22` . `66`? \$/&returns true,\cr "aaad" =~ / "a"+ "b"* "c"? "d" \$/&returns true,\cr "@q@q" =~ / (`40` "q")+ \$/&returns true,\cr "wxyz" =~ / "w" ("xy" | "yx") "z" /&returns true,\cr "abccbd" =~ / "a" ["bc"]+ "d" /&returns true, and\cr "abccbd" =~ / [^"bc"] "bccb" [^"bc"]&returns true.\crcr After a successful match, substrings of the matched string can be extracted. The variable \($0\) holds the portion of the string that matched the regular expression, \($1\) holds the portion of the string that matched the first parenthesized subexpression in the regular expression, \($2\) holds the second, and so on. Thus, after the first of the above examples, \($0\) holds \(`00112233`\) and \($1\) holds \(`0011`\). After the match \centerline{\("abcbcbcdddde" =~ / ("a" ("bc" *)) ("d"+) /\)} \noindent returns true, \($0\) holds \("abcbcbcdddd"\), \($1\) holds \(abcbcbc\), \($2\) holds \("bcbcbc"\), and \($3\) holds \("dddd"\). This behavior is useful for parsing. \section{SOTL Expressions} SOTL expressions contain operators, identifiers, integer constants, string constants, and time constants. Operators include most of the C operators, and also a considerable set of keyword prefix operators, called ``commands.'' Each command can be abbreviated when it is the first thing on a line. A description of each command appears below. \subsection{SOTL Operators} SOTL supports most C operators, and uses the same precedence rules. However, some operators are overloaded and have different meanings in different contexts, for the convenience of the SOTL programmer. In the following section, {\it x}, {\it y}, and {\it z} represent expressions (which presumably contain no operators of lower precedence than the ones being demonstrated.) Precedence rules are the same as in C. The operators are presented here in order from low to high precedence. All standard C prefix operators actually have the same precedence, and all postfix operators all have the same (highest) precedence. There are a few infix operators that are higher precedence than the prefix operators. \def\x{{\it x}} \def\y{{\it y}} \def\z{{\it z}} \leftskip = 0.5in \def\thingy#1{\par\noindent\hbox to 0pt{\hskip -1.0in \it #1\hss}} \def\Command#1{\smallskip\thingy{Command}{\tt #1}} \def\Abbreviated#1{\thingy{Abbreviated}{\tt #1}} \def\Example{\thingy{Example}} \def\Description{\thingy{Description}} \def\SystemCall#1{\thingy{System Call}{\tt #1}} \def\Type#1{\thingy{Type}{\tt #1}} \def\Details#1{\thingy{Details}{\it #1}} \def\Constructor{\thingy{Constructor}} \def\Predicate#1{\thingy{Predicate}{\tt #1}} \def\Meaning{\thingy{Meaning}} \def\construction{\(\doconstruction{Construction}} \def\Statement{\(\doconstruction{Statement}} \def\doconstruction#1#2\crcr{{\singlespace\thingy{#1}% \noindent\hbox{\vtop{\halign{\tt ##\hfil\cr #2\crcr}}}}\par\)} \construction \x\ = \y\cr \x\ += \y\cr \x\ -= \y\cr \x\ *= \y\cr \x\ /= \y\cr \x\ %= \y\cr \x\ >>= \y\cr \x\ <<= \y\crcr \Meaning \y\ is evaluated. In the first case, the result is assigned to \x; in the second, it is added to \x; and so on. \construction \x\ ?\ \y\ !\ \z\crcr \Meaning \x\ is evaluated. If it is true, then \y\ is evaluated and returned; otherwise, \z\ is evaluated and returned. Note that \(!\) is used instead of \(:\). This is because \(:\) already has several other meanings, and overloading it further is not feasible. \construction \x\ || \y\crcr \Meaning \x\ is evaluated. If it is true, it is returned. Otherwise, \y\ is evaluated and returned. Note that this is more like the Lisp meaning of the \(or\) operator than the C meaning; in C, the return value is always 0 or 1. \construction \x\ && \y\crcr \Meaning \x\ is evaluated. If it is false, it is returned. Otherwise, \y\ is evaluated and returned. \construction \x\ | \y\crcr \Meaning \x\ and \y\ are evaluated and their bitwise-or is returned. \construction \x\ ^ \y\crcr \Meaning \x\ and \y\ are evaluated and their bitwise-xor is returned. \construction \x\ & \y\crcr \Meaning \x\ and \y\ are evaluated and their bitwise-and is returned. \construction \x\ == \y\cr \x\ != \y\cr \x\ =~ \y\cr \x\ !~ \y\crcr \Meaning \x\ and \y\ are evaluated. In the first two cases, \(==\) and \(!=\), if they are dwords or time values, they are compared numerically. If they are strings, they are considered equal if they have the same length and each character is the same. For \(==\), if they are equal, then 1 is returned; otherwise, 0 is returned. Conversely for \(!=\). In the second two cases, \x\ must be a string and \y\ must be a pattern. For \(=~\), true is returned if the string matches the pattern, and false otherwise. Conversely for \(!~\). \construction \x\ <= \y\cr \x\ >= \y\cr \x\ > \y\cr \x\ < \y\crcr \Meaning \x\ and \y\ are evaluated and compared. They must be dwords or time values. If the comparison is true, then 1 is returned; otherwise, 0 is returned. \construction \x\ + \y\cr \x\ - \y\crcr \Meaning \x\ and \y\ are evaluated and added (or subtracted). They must be dwords or time values. If only one is a time value, the result is another time value; when promoting a dword to a time value, the dword is taken to be a number of ticks. \Example \(100 + 1:2.3\) \yields(1:2.103) \construction \x\ :\ \y\crcr \Meaning If \x\ is a dword and \y\ is a dword, then another dword is returned using the formula \((x << 16) + y\) (this is for {\it segment}\(:\){\it offset} notation). If \x\ is a dword and \y\ is a time value (usually in the form $a\(.\)b$), then a time value $x\(:\)a\(.\)b$ is created (this is for time value constants). If \x\ is a source code module and \y\ is a dword, then the address of line \y\ of module \x\ is returned (this is for line number references). If \x\ is a machine and \y\ is a symbol, then the address of symbol \y\ in machine \x\ is returned (making it possible to override the current machine when a symbol is being looked up). \construction \x\ * \y\cr \x\ / \y\cr \x\ % \y\crcr \Meaning \x\ and \y\ are evaluated, and their product, quotient, or remained of division is returned. \construction + \x\crcr \Meaning An address \x\ bytes from the top of the current function is returned. \construction :\ \x\crcr \Meaning The address of line \x\ in the current module is returned. \construction ~ \x\cr - \x\cr !\ \x\crcr \Meaning The binary, two's complement, or boolean negation of \x\ is returned. \construction & \x\cr * \x\crcr \Meaning These are pointer operators as in C. Note that \x\ must be a reference to a target data object in the first case, and a pointer to a target data object in the second. You may not take the address of a SOTL object; SOTL itself does not have a pointer type. These operators can only be used when target debugging information is available. \construction ++ \x\cr -- \x\crcr \Meaning \x\ is evaluated; the result is incremented (or decremented), stored back in \x, and returned. \construction \x\ -> \y\crcr \Meaning \x\ is evaluated, and must be a pointer to a target data object that is a structure. \y\ must be a single indentifier, and is interpreted as a field of the structure. A reference to the field is returned. \construction \x\ .\ \y\crcr \Meaning \x\ is evaluated. If \x\ is a reference to a target data object that is a structure, then \y\ must be a single indentifier, and is interpreted as a field of the structure; a reference to the field is returned. If \x\ is a string, then \y\ must be a string, and their concatenation is returned. Otherwise, \x\ and \y\ must be dwords, in which case a time object with \x\ seconds and \y\ ticks (0:\x.\y) is returned. \construction \x\ [ \y\ ]\crcr \Meaning \x\ is evaluated, and must be either a SOTL array, a SOTL string, a reference to a target data object that is an array or a pointer, or a pointer to a target data object. \y\ is evaluated, and must be a dword. If \x\ is a SOTL array, a reference to the SOTL object stored an the array is returned. If \x\ is a SOTL string, the byte stored in that position of the string (or -1 if \y\ i out of range) is returned. If \x\ is a target array, a target pointer, or a pointer to a target object, a reference to the appropriate target data object is returned. \construction \x\ ( arg1, arg2, ... )\crcr \Meaning \x\ is evaluated, and must be a SOTL function. The arguments are all evaluated, and the values are passed to \x. The result of the final evaluation in \x\ is returned. \construction \x\ ++\cr \x\ --\crcr \Meaning \x\ is evaluated and its value is returned. Then, that value is incremented (decremented) and stored back in \x. \construction .\crcr \Meaning The current value of \(CS:IP\) is returned. \construction _\crcr \Meaning The top of the current function is returned. This is the same as \(+ 0\). \construction [ \x\ ]\cr [ \x\ , \y\ ]\crcr \Meaning An object representing a block of target memory is created. The address is \x, and the size is \y\ if specified, and 4 if not. If the size is 1, 2, or 4, then this reference promotes automatically into a dword whenever a dword is needed. This promotion will generate a memory read event. Blocks are useful with the print command (see below) and can also be converted into strings. \Example \(enterbyte 100, 123; x = [100, 1]; print x, " = ", x + 0;\)\\ \bigyields([0000:0064 , 1] = 123) \construction ( \x\ )\crcr \Meaning \x\ is evaluated and returned. This construction exists to override operator precedence. \construction { statement; statement; ... }\crcr \Meaning The statements are executed and the result of the final statement is returned. \Example \(x = { while (1) ..... };\) \leftskip = 0pt \section{SOTL Statements} There are very few statements in SOTL. As in C, most things that you might think of as statements (such as printing things, setting breakpoints, and so on) are actually expressions. There are, in fact, only five statements, and two are trivial. \leftskip = 0.5pt \def\e{{\it expression}} \def\s{{\it statement}} \def\n{{\it name}} \def\a#1{$arg_{#1}$} \Statement \e ;\crcr \Meaning Evaluate the expression. If this is the last statement of a procedure, then its value is the return value for the procedure. Otherwise, the value is thrown away. \Statement ;\crcr \Meaning This is the empty statement, and has no effect. \Statement if \e\ { \s; ... }\cr if \e\ { \s; ... } else { \s; ...}\cr if \e\ { \s; ... } elsif \e\ ...\crcr \Meaning The expression is evaluated. If it is true, the first block is evaluated and its final value returned. Otherwise, there are three cases. If there is an else clause, then the else block is evaluated and its final value returned. If there is an elsif clause, it is treated just like an if. If there is no clause, then \(nil\) is returned. Unlike in C, the then-clause and else-clause must be grouped in curly-braces, even if there is only one statement. \Statement while \e\ { \s; ... }\crcr \Meaning The expression is evaluated. If it is true, the block is evaluated and the expression is checked again. If it is false, its value is returned. Note that while statements always return false. \Statement def \n\ ( \a1, \a2, ... ) { \s; ... }\crcr \Meaning This statement creates a SOTL function and assigns it to the given name. This statement always returns \(nil\). \leftskip=0pt \section{SOTL Command Operators} SOTL commands are actually prefix operators. Unlike the other (more typical) prefix operators like \(++\), which operate only on the term immediately on their right, SOTL prefix operators can grab several whole expressions separated by commas. They have the lowest precedence of any operator. Many commands operate on a machine. While a few commands explicitly take a machine as an argument, most commands work on the ``current machine.'' Each thread has its own notion of what the ``current machine'' is; the current machine is preserved through procedure calls. Many command operators can be abbreviated. These abbreviations are only recognized if the command is the first non-whitespace item on a new line. Abbreviations are meant to be used only at top-level, although they may be used in SOTL source files as well. Many command operators take one or more arguments. These arguments may optionally be enclosed by parentheses. But beware: some examples should make clear the unexpected results this convenient syntax can sometimes cause. {\singlespace \leftline{\hskip 0.5in\hbox{\vbox{\halign{{\tt #}\hfil\quad &\vtop{\vtop{\hsize=4in\noindent #}\vskip 3pt}\hfil\cr \it Expression&\it Meaning\cr \noalign{\vskip 2pt\hrule\vskip 2pt} foo 2,3&Apply the \(foo\) operator to 2 and 3\cr foo (2,3)&Same as above\cr foo (2,3) + 4&Apply the \(foo\) operator to 2 and 3, and add four to the result\cr (foo 2,3) + 4&Same as above\cr foo 2,3 + 4&Apply the \(foo\) operator to 2 and 7. This may not be what you meant; you probably meant the above.\cr foo 1+2*3&Apply the \(foo\) operator to 7\cr foo (1+2*3)&Same as above\cr foo ((1+2)*3)&Apply the \(foo\) operator to 9\cr foo (1+2)*3&Apply the \(foo\) operator to 3, and multiply the result by 3. This is certainly not what you meant!\cr }}}}} \medskip As you can see, this is tricky. If you want to be safe, always parenthesize the intended arguments of command operators. \leftskip=0.5in \Command{break} \Abbreviated{b} \Example\(break _main, 0:10.23, memorywrite(_foo, _foo+20)\) \Description Allows the user to specify what events are of interest. When one of these events is received, it causes a ``break.'' A message describing the event is printed, the foreground thread is killed, all freezable threads are frozen, and control is returned to top-level as if the user pressed control-C. \(break\) takes a comma-separated list of event specifications as its argument; see the section on event specifications for more information. \Command{breaklist} \Abbreviated{bl} \Description Lists the events specifications that will cause breaks. They are listed with numbers that can be used to refer to them. This command takes no arguments. \Command{breakdelete} \Abbreviated{bd} \Example\(breakdelete 2, 3\) \Description Takes a comma-separated list of numbers as its argument, and deletes the event specifications with those numbers. \Command{breaknow} \Abbreviated{bn} \Description Allows a thread to signal a break. When any thread executes this command, a message is printed, the foreground thread is killed, all freezable threads are frozen, the user is returned to top level. \Command{backtrace} \Abbreviated{bt} \Description Divides the stack of the current machine into its frames, and for each frame prints the name of the procedure and the values of its arguments. Frame 0 is the innermost (deepest) frame; frame 1 is the frame of frame 0's caller, frame 2 is frame 1's caller, and so on. This command is only avaiable if the target has been compiled with debugging information. It takes no arguments. \Command{blockuntil} \Abbreviated{bu} \Example\(blockuntil messagereceive, portread(0x400)\) \Description Has two functions. First, it subscribes to events the current thread is interested in receiving. Second, it blocks the thread. When an event matching one of the event specifications is received, the thread will unblock. Like \(break\), its arguments are event specifications. \Command{call} \Abbreviated{c} \Example\(call _printf\) \Description Initiates a target procedure call. The registers and flags are saved, \(CS:IP\) is set to the given address, and the thread blocks until the call returns. When the target function returns, the thread unblocks, and the value of the call operator is the value of DX:AX. Then the registers and flags are restored. This operator is a hack. Do not use it if you can think of any way around it. If the thread dies before the call returns, chaos ensues, and SOTEST will probably crash. I will probably either fix this soon, or delete the call mechanism. \Command{chdir} \Abbreviated{cd} \Example\(chdir "/tmp"\) \Example\(print chdir\) \Description With a string argument, it changes SOTEST's notion of the current working directory. In any case, the current working directory is returned as a string; the second example above prints the current working directory. \Command{clockclear} \Abbreviated{cc} \Description Clears the value of the clock for each machine. It also sets the record of the amount of host CPU time used by SOTEST to 0. \Command{clock} \Description Returns the value of the clock for the current machine. \Command{copy} \Abbreviated{cp} \Example\(copy _my_data, _your_data, 100\) \Description Copies memory from the first address given to the second addres given; the third argument is the number of bytes to copy. Overlapping copies are supported. No memory write events are generated for the copy. \Command{defined} \Abbreviated{df} \Example\(defined $my_symbol\) \Description Tests if the given symbol is defined. If it is defined in any way --- as a SOTL variable, a target local symbol, a machine register, or the name of a code module, for example --- the operator returns 1. Otherwise, it returns \(nil\). \Command{dmarequest} \Abbreviated{dr} \Example\(dmarequest $channel, 1\) \Description Sets the value of the DMA request line (DRQ0 or DRQ1) for the given channel, which must be 0 or 1. The second argument must be true or false. If a DMA channel is synchronized, then DMA is allowed only if this value is true. This value is not used if the DMA channel is unsynchronized. See documentation about the 80186 family of processors for more information on the DMA controller. \Command{down} \Abbreviated{dn} \Description Moves down one stack frame. This is available only if the module was compiled with debugging information. \Command{dump} \Abbreviated{d} \Example\(dump es:0x1234\) \Description Displays 128 bytes of memory starting at the given address. If the address is omitted, the next 128 bytes are displayed. No memory read events will be generated for the memory displayed. If a memory location is under examination by one or more threads, a \(?\) will be displayed after the value, meaning that the value displayed is not necessarily what an instruction reading the location would see. In this case, the value displayed is merely the last value written to the address. \Command{enterbyte} \Abbreviated{eb} \Example\(enterbyte 0x1234:10, 1, 2, 3, 4\) \Description Enters bytes into memory. The first argument is the starting address; the remaining arguments are bytes to enter, each at the next address. Memory write events are generated for these writes, but will not be processed until the thread blocks. \Command{eval} \Abbreviated{ev} \Example\(eval ev = 10, pdq = 20\) \Description Evaluates a list of expressions. This takes the place of the C comma operator. Also, it works around the rare case when you want to begin an expression whose first term is a command abbreviation. Note that while the command \(eval g = 10\) does what you want (sets variable \(g\) to 10), typing \(g = 10\) alone does not. You can also work around this with parentheses, by typing \((g = 10)\). \Command{enterword} \Abbreviated{ew} \Description Like enterbyte above, except it stores words in every other address starting from the one specified. \Command{fill} \Abbreviated{f} \Example\(fill cs:0, cs:0xfffe, 123\) \Description Fills a range of memory with a single byte quickly, without generating memory write events for memory modified. The three arguments are the starting address, the ending address, and the byte to fill with. Note that the ending address is exclusive, {\it i.e.,} \(fill 10, 10, 123\) is a no-op, whereas \(fill 10, 11, 123\) writes one byte. \Command{flag} \Abbreviated{fl} \Example\(flag if = 1\) \Example\($overflow = flag of\) \Description Returns the value of an 80186 flag. If used as an lvalue, it changes the value of a flag. Legal flags are: {\singlespace\halign{\hskip 2in\tt #\quad& #\hfil\cr cf & Carry flag\cr pf & Parity flag\cr af & Auxiliary flag\cr zf & Zero flag\cr sf & Sign flag\cr tf & Trace (single-step) flag\cr if & Interrupt-enable flag\cr df & Direction flag\cr of & Overflow flag\cr}} \medskip \Command{fork} \Abbreviated{fo} \Example\(fork my_function(1, 2, 3)\) \Example\(fork { while (1) { ... } }\) \Description Creates a new thread, which runs evaluating the expression given. The current values of SOTL local variables are copied for the new thread, so you can use locals variables inside the expression. The thread begins life runnable and unfrozen, and will start to run immediately; the current thread effectively ``blocks'', but will run again once the forked thread blocks or exits. This operator returns the thread ID of the new thread. \Command{format} \Example\($mystr = format "X is ", %b x, " (decimal ", %d x, ")"\) \Description Formats SOTEST objects for output. It is exactly like \(print\), except that instead of writing the result to standard output, it returns the result as a string. No newline is added to the string. See \(print\) below for more information. \Command{getthreadid} \Description Returns the thread ID of the current thread as a dword. \Command{go} \Abbreviated{g} \Example\(go cs:ip+12\) \Description Unfreezes all frozen threads and then blocks until an event is received. At that point, it will print out the state of the current machines just like the machinelist operator. With no arguments, it will never return a value; the thread running it will block until it is killed. It is usually used from top-level, indicating that the user is ready to proceed with execution of background threads and the machines. It is not usually used from threads; blockuntil is more common, because it doesn't have the side effects of unfreezing other threads and printing out machine state. \Command{global} \Abbreviated{gl} \Example\(global \x, \y\) \Description Declares variables global without assigning them values. (Actually, if the global variable doesn't already exist, it creates it and assigns \(nil\).) This is useful within SOTL functions, because within a function an assignment to an undefined variable causes the variable to be created local. \Command{heapalloc} \Abbreviated{ha} \Example\(heapalloc 12\) \Description Allocates memory from the current machine's heap, and returns its address. The argument to heapalloc specifies the size of the allocation. There is no way to free memory allocated in this way, other than redefining the heap. \Command{heapdefine} \Abbreviated{hd} \Example\(heapdefine 0xf000:0, 0x1000\) \Description Defines a range of memory for use as a heap. Typically, this will be memory that the target never uses. \Command{historysize} \Abbreviated{hs} \Example\(historysize 40\) \Description Sets the number of history records SOTEST keeps, or, with an argument of 0, cancels history recording. If history recording is on, SOTEST keeps records of when memory is read or written, when ports are read or written, when instructions are fetched for execution, and when control is transferred from one point in the program to another. These records can be displayed with the \(printhistory\) command below. \Command{inbyte} \Abbreviated{ib} \Example\(inbyte 0x60\) \Description Reads a byte from a port. Although this command does generate a port read event, the thread subscribing to it will not receive it at least until after the \(inbyte\) operator finishes; thus, in general you will get the value last read from that port as opposed to any value that thread may supply. The value read is returned; thus, to see the value read from a port, do something like \(print %b inbyte 0x1234\) \Command{interrupt} \Abbreviated{in} \Example\(interrupt 0x38\) \Description Generates an interrupt. If the vector type is not a hardware interrupt vector type, this blocks until the current machine's interrupt flag is set and then generates an interrupt of the given vector type, just as if the machine had just executed an \(INT\) instruction. If the vector is a hardware vector, the interrupt is scheduled through the simulated interrupt controller, and the operator returns immediately. \Command{inctimer} \Abbreviated{it} \Example\(inctimer 1\) \Description Advances the timer with the given number, as if it had received a strobe on its external clock line. This may generate an interrupt; if so, the interrupt is scheduled through the interrupt controller. \Command{inword} \Abbreviated{iw} \Description Just like inbyte, except it reads a word from the port. \Command{length} \Example\(length "foo"\) \Description Returns the length of its argument. If the argument is a string, this is the number of characters in the string. If the argument is a block, this is the number of bytes in the block. If the argument is an array, this is the number of elements in the array (one more than the array's highest index.) \Command{load} \Abbreviated{l} \Example\(load "test.abs"\) \Description Loads an absolute object file into the current machine, and processes its debugging information. \Command{local} \Abbreviated{lo} \Example\(local x, y\) \Description Declares the named variables local. If the variables do not already exist locally, they are created and \(nil\) is assigned to them. Even though variables are created locally by default, it is still a good habit to always use local to declare variables. The reason is that if a variable exists globally, the first assignment to that variable in your function will not create the variable locally as you might expect, but rather will assign to the global variable. \Command{machine} \Abbreviated{m} \Example\(machine Processor2\) \Description Sets the current function's notion of the current machine to the machine given as its argument. Once this command is issued, operators which operate on machines ({\it i.e.,} most operators, {\it e.g.,} \(enterbyte\) and \(memoryfetch\)) will operate on the given machine. The old current machine is restored when the function exits. \Command{machinecreate} \Abbreviated{mc} \Description Takes no arguments. It creates a new machine, allocates memory to simulate target memory and ports, and sets the current machine to the new machine. Once a machine is created, there is no way to destroy it except by quitting SOTEST. \Command{machineidle} \Abbreviated{mi} \Description Declares the current machine idle, sending events to threads waiting for the machine to go idle. It takes an optional argument that identifies the machine's idle point; the machine remains idle as long as \(CS:IP\) is equal to this idle point. If the idle point is omitted, then the current value of \(CS:IP\) is used. The typical way to use \(machineidle\) is to create an idle-detecting thread as follows: \code fork { while (1) { blockuntil _idle_task; machineidle _idle_task; } }; \code If you do not specify the idle point, it is possible that the idle-detecting thread will unblock at precisely the same time as a thread that generates an interrupt on the machine. In that case, you may inadvertently declare the machine idle at the start of the interrupt handler. Thus, it is a good habit to always explicitly specify the idle point. SOTEST keeps track of the amount of time that elapses with the machine declared idle. You can use this to measure the loadware's percent CPU utilization. The \(printclock\) operator will display the utilization. \Command{machinelist} \Abbreviated{ml} \Description Prints the state of each machine: its name, the values of its registers and flags, and whether or not the machine is idle. \Command{machinename} \Abbreviated{mn} \Example\(machinename Processor1\) \Description Changes the name of the current machine to the name given. The name given must not already be in use. \Command{mapPCB} \Abbreviated{mp} \Example\(mapPCB 0x8000:0\) \Description Memory-maps the 80186 peripheral control block (PCB) at the given addres. Normally, the PCB is port-mapped at port \(0xff00\). \Command{memoryfetch} \Abbreviated{mf} \Example\($foo = memoryfetch [0x1234h:0x5678h, 10]\) \Description Takes a block as an argument. It reads the bytes from the block, generating memory read events, and assembles them into a string, which it returns. Note that this is not a particularly convenient way to view the contents of a block; you are better off using \(dump\) or \(print\). \Command{messagesend} \Abbreviated{ms} \Example\(messagesend $thread, "hello there"\) \Description Sends a message to a thread. The first argument is a thread ID number, usually the return value of fork. The second argument is the message, which may be any SOTL object; typically, dwords, strings, or arrays are sent. If the thread specified does not exist, or is not subscribed to \(messagereceive\) events, the message is dropped and a false value is returned; otherwise, a true value is returned. \Command{microseconds} \Example\(microseconds 0:1.0 \yields(1000000)\) \Description Converts a time value a dword, which is the number of microseconds (rounded down) that the time value represents. If its argument is a dword, it is interpreted as a number of ticks; {\it i.e.,} \code microseconds $foo \code is equivalent to \code microseconds 0:0.$foo \code The exact operation performed depends on how fast your processor is. For a 16 MHz processor, the operation is (more or less) a simple divide by 16. \Command{outbyte} \Abbreviated{ob} \Example\(outbyte 0xff3e, 0\) \Description Sends a byte to a port, and generates a port write event. \Command{outword} \Abbreviated{ow} \Description Sends a word to a port, and generates a port write event. \Command{pack} \Abbreviated{pk} \Example\(pack 0x100:0, "CSL", 10, 1000, 10000000\) \Example\($packet = pack "nN", 1000, 10000000\) \Description Stores dwords in sophisticated ways. Pack has two forms. In the first form, the first argument is a dword, and it indicates a target address. The second argument, called the control string, is a string indicating how to store the remaining arguments, in the spirit of \(printf\). The remaining arguments are dwords to be stored. The return value is the address where pack stopped; that is, the number of bytes written can be calculated as follows: \code $end = pack $addr, "v??V", 300, 123456789; $numpacked = $end - $addr; \code Each character in the control string explains what to do with the next dword to be packed. For example, \(c\) means to interpret the dword as a \(signed char\); one byte is stored at the current address, and the address is bumped up by one. \(N\) means to interpret the dword as an \(unsigned long\), and pack it as four bytes in network (big-endian) byte order, most significant byte first. {\singlespace\halign{\hskip 0.75in{\tt #}\quad\hfil&#\hfil\cr c&signed character\cr C&unsigned character\cr s&signed short (target byte order)\cr S&unsigned short (target byte order)\cr i&signed int\cr I&unsigned int\cr l&signed long (target byte order)\cr L&unsigned long (target byte order)\cr v&unsigned short, Vax (little-endian) byte order\cr V&unsigned long, Vax (little-endian) byte order\cr n&unsigned short, network byte order\cr N&unsigned long, network byte order\cr x&don't take an argument; pack a null (0) byte\cr ?&don't take an argument; skip forward a byte\cr X&don't take an argument; back up a byte\cr p&pack the next argument according to target alignment constraints\cr P&pack the next argument according to host alignment constraints\cr}} \medskip In these examples, address 0 is used with pack, and the results shown are the bytes stored at address 0 after the pack. \code pack 0, "CCC", 1, 2, 3 \smallyields(01 02 03) pack 0, "S", 1234h \smallyields(34 12) pack 0, "SL", 0102h, 010203h \smallyields(02 01 03 02 01 00) pack 0, "cxi", 100, 1000 \smallyields(64 00 E8 03) pack 0, "cxv", 100, 1000 \smallyields(64 00 E8 03) pack 0, "cxn", 100, 1000 \smallyields(64 00 03 E8) pack 0, "cXc", 100, 7 \smallyields(07) \code In the second form of pack, the address is omitted, the first argument is the control string, and the remaining arguments are dwords to be stored. In this case, a string is created containing pack's result and target memory is unchanged. Typical uses for this form include future storage with enterbyte, display with print, and message passing. \code $mystring = pack "xxxx"; \yields(string of 4 nulls) pack "CC", 104, 105 \yields("hi") \code You may notice a redundancy: the first form of pack can be accomplished with the second form of pack and enterbyte. That is, \code pack $addr, "...", ... \code is equivalent to \code enterbyte $addr, pack "...", ... \code \Command{print} \Abbreviated{p} \Example\(print "N is ", %b n, "!"\) \Description Displays SOTL and target data in a user-readable form. The arguments are SOTL expressions, optionally preceeded by a format specifier. The format specifiers are: {\singlespace\halign{\hskip 1in{\tt\%#}\quad\hfil&#\hfil\cr d&Format as signed decimal\cr u&Format as unsigned decimal\cr b&Format as array of hex bytes (chars)\cr w&Format as array of hex words (shorts)\cr l&Format as array of hex dwords (longs)\cr p&Format as array of pointers to target memory\cr s&Format as source code location\cr}} How an object displays depends on the type of the object and the format specifier. Dwords normally display as signed decimal, but can be displayed in hex by using \(%b\), \(%w\), or \(%l\), or as a pointer with \(%p\), or as a source code location with \(%s\): \code print %b 100 \yields(64) print %p 5ec2h:14 \yields(5EC2:000E _idle idle:168) print %s 5ec2h:14 \yields(5EC2:000E _idle idle:168) \code The difference between the second and third example is that in the third example, in addition to printing the location, SOTEST sends a message to the SOTEST front end to display the source code at the given location. By default, blocks display as $[address , size]$, but can be displayed much more interestingly with format specifiers. In general, using a format specifier causes display of the contents of the memory to which the block refers. No memory read events will be generated when the memory is displayed. Examples should make this clear: \code enterbyte 1, 1, 2, 3, 4, 5, 6, 7, 8; x=[1,8]; print x \yields([0000:0001, 8]) print %b x \yields(01 02 03 04 05 06 07 08) print %w x \yields(0201 0403 0605 0807) print %l x \yields(04030201 08070605) \code By default, references to target data object display symbolically; for example, a printing a reference to a structure displays its fields and their values. You can control the number of array elements that will be displayed by setting the magic global variable \($MaxArrayElems\). If you use \(%b\), \(%w\), or \(%l\), the target object will be displayed as an array of hex bytes, words, or dwords; since SOTL knows the size of the target object, it knows how many numbers to print. No memory read events will be generated when target data objects are displayed. By default, strings are printed in ASCII. However, strings can be formatted as arrays with \(%b\), \(%w\), or \(%l\): \code print "foo ", %b "foo " \yields(foo 66 6F 6F 20) \code Other data types format very simply, and ignore their format specifier. For example: \code machinename FooMachine print FooMachine \yields() \code \Command{printsegments} \Description Dumps the segment definitions for the current machine. Segment names, classes, addresses, and sizes are displayed. This is basically the same information as you find in the linker's map file. \Command{printclock} \Abbreviated{pc} \Description Prints the value of the clock ({\it i.e.,} the number of 80186 clock cycles since SOTEST started), how much of that time was spent with the processor declared idle (see the \(machineidle\) operator), the amount of host CPU time used by SOTEST, and a comment about SOTEST's performance. \Command{printdma} \Abbreviated{pd} \Description Prints the state of the 80186 DMA controller. For each channel, it prints the source and destination pointer, the synchronization type, the status of the DMA request lines (DRQ0 and DRQ1), and other miscellany about the channel. Use the \(dmarequest\) operator to manipulate the DMA request lines. \Command{printframe} \Abbreviated{pf} \Description Prints the current stack frame. This is avaiable only if you have compiled with debugging information. It displays the values of all parameters and local variables, and displays the return address and current execution address for the frame. \Command{printhistory} \Abbreviated{ph} \Example\(printhistory 15\) \Description Prints recent history records. If an argument is specified, only that many are printed; otherwise, all records are printed. Records are printed from oldest to most recent. The \(historysize\) command must be issued first, to specify how many history records to keep. \Command{printinterrupts} \Abbreviated{pi} \Description Prints the state of the 80186 interrupt controller. For each interrupt, it shows the address of its interrupt procedure, whether the interrupt is masked, pending, or in service, and the interrupt's priority. \Command{printstack} \Abbreviated{ps} \Description Crawls the 80186 stack, hoping that every procedure is a far procedure. This is available even without debugging information. It attempts to print the return addresses of procedures, their locals, and their parameters, but without type information and local variable information the rendition is ugly at best. However, if you're stuck without debugging information, it's better than nothing! \Command{printtimers} \Abbreviated{pt} \Description Prints the state of the 80186 timer block. For each timer, it prints its value, whether it is enabled, whether it is signalled internally or externally, and value of its thresholds. \Command{processor} \Abbreviated{pr} \Description Configures the current machine's microprocessor. The first argument is a subcommand name; the remaining argument depends on the subcommand. Subcommands are: {\singlespace \halign{\tt #\hfil\quad&#\hfil\cr I80186 & The current machine is an 80186. No more arguments.\cr I80188 & The current machine is an 80188. No more arguments.\cr clockspeed & Sets the current machine's clock speed to the given \cr & value, in ticks per second.\cr waitstates & Sets the number of wait states required for memory\cr & access. Each wait state is one clock tick.\cr info & Displays the configuration of the current machine's processor.\cr }} \medskip Examples: \code processor I80186; processor I80188; processor clockspeed, 16000000; # 16 megaherz processor waitstates, 4; # 4 wait states processor info; \code \Command{random} \Example\(random 10\) \Description Returns a random number. If an argument is given, the number returned will be between 0 and its argument minus one; e.g, random 10 returns a number from 0 to 9. If not, the random number will be between 0 and $2^{32} - 1$. \Command{readline} \Example\($line = readline $filedesc;\) \Example\($userinput = readline;\) \Description Returns a string read from a file. If a file descriptor is specified, the line is read from that file inefficiently, using lots of \(read\)(2) system calls, one character at a time. If a newline is hit, it terminates the line but is not included in the string read. If \(EOF\) is hit, it terminates a non-empty line. If \(EOF\) is hit at the beginning of the line, the value \(nil\) is returned. If no file descriptor is given to \(readline\), the line is read using \(stdio\)'s \(fgets\)(3) from SOTEST's standard input (not the file being read by \(<\)). The string is returned, unless \(fgets\)(3) returns \(NULL\), in which case the \(nil\) is returned. \Command{reassigndebsym} \Example\(reassigndebsym 0x40e2, DFE_CODE\) \Example\(reassigndebsym _dfe_intr_ul\) \Description This unfortunate command exists to work around a bug in SOTEST. SOTEST is not always able to correctly associate debugging information with its corresponding code segment. If there's a public procedure \(foo\) which should, but doesn't seem to, have debugging information, try this: \code print &foo; print _foo; \code You will see two addresses. If they have the same offset but different segments, then the reason that \(foo\) doesn't seem to have debugging information associated with it is because of SOTEST's bug. To work around this bug, merely type \code reassigndebsym _foo; \code \noindent and all should be well. If it isn't, here's another much more involved strategy. First, you will need to find the DEBSYM segment which actually contains the debugging information for \(foo\) (the \(printsegments\) and \(print %p search\) commands can help you). You also need to know the name of the segment in which \(foo\) is located (use \(printsegments\) and \(print %p _foo\) to find out). When you find the segment address of the \(DEBSYM\) segment, and the name of the code segment, do \code reassigndebsym debsym-segment-address, code-segment-name \code \noindent as in \code reassigndebsym 0x44e2, MY_CODE \code \noindent Then the test \code print &foo; print %p _foo; \code \noindent should print the same exact address twice. \Command{register} \Abbreviated{r} \Example\(r cs:ip = 0x1000:0x2000\) \Description Displays or sets registers on the current machine. With no argument, the registers and flags are displayed. The argument can be in the form $reg=value$ or $reg:reg=value$. In the first case, the given register is set to the given value. In the second case, the first register is set to the segment portion (upper 16 bits) of the given value, and the second register is set to the offset portion. \Command{return} \Example\(return "hello"\) \Description Exits the current SOTL function, returning the given value. \Command{search} \Abbreviated{s} \Example\(search _start, _end, 10, 20, 30\) \Description Searches the given range of memory for the given sequence of bytes, returning the first address where the sequence was found. It does not generate read events for any memory read. \Command{srandom} \Example\(srandom 123\) \Description Seeds the random number generator. With an argument, the argument is used as the seed. Without an argument, the current system time is used as the seed. \Command{string} \Example\(string 10, "hello", 0xff, 0, [_my_data, 20]\) \Description Constructs a string out of a list of arguments. The arguments may either be dwords, strings, or blocks. Dwords are converted to strings of length one, whose single byte is the least significant byte of the given dword. Blocks are converted to strings whose bytes are the bytes that make up the block (no memory read events are generated). Then the whole list is concatenated together. \code print %b string 10, "abc", 0 \smallyields(0A 61 62 63 00) print string "hi", 32, "there" \smallyields(hi there) \code \Command{stringvalue} \Example\(stringvalue "A43", 16\) \Description Converts from a string to a dword. An optional second dword argument is the base, which defaults to decimal. \(0x...\) and \(...h\) syntax are not recognized. \Command{substr} \Example\(substr "hello there", 3, 2 \yields("lo")\) \Description Extracts a portion of a string. The second argument is the starting position (0 is the first character); the third argument is optional, and is the number of characters to extract. If omitted, characters up to the end of the string are extracted. \Command{sourcedir} \Abbreviated{sd} \Example\(sourcedir "/build/mysources:/tmp:."\) \Description Specifies the directories that SOTEST will look in when trying to find source files. It takes a single argument which must be a string; it is a colon-separated list of pathnames similar to the \(PATH\) environment variable. When SOTEST locates a point in your source code, it will search the directories you specify here to find your source file and tell the SOTEST front end to display it. If you don't use a front end, then your source is never displayed; see the section below on SOTEST front ends for more information. The \(sourcedir\) operator returns the source directory list as a string, so the current source director list can be displayed with the command \code print sourcedir \code \Command{threaddebug} \Abbreviated{td} \Description Puts a thread in debug mode. Such threads will be frozen when the user gains control; they will continue to queue events, but they will be processed only when the user unfreezes the thread (either explicitly with \(threadunfreeze\) or by using the \(go\) command). A misbehaving ({\it i.e.,} continuously-running) thread not in debug mode will keep the user from being able to do anything, but when in debug mode the user will be able to regain control with control-C. When a thread in debug mode receives an event, a warning message is printed. \Command{threadexamine} \Abbreviated{te} \Example\(threadexamine getthreadid\) \Description Displays a considerable amount of information about the given thread. This is often useful for debugging SOTL programs. \Command{threadlist} \Abbreviated{tl} \Description Lists all threads, their thread ID, their state, whether or not they're frozen, whether or not they have events queued, their name, and where they were started from. You can get more information about a thread by with the command \(threadexamine\). \Command{threadcont} \Abbreviated{tc 12} \Description Continues a thread that has been stopped by \(threadstop\). \Command{threadkill} \Abbreviated{tk} \Example\(threadkill 10, 11, getthreadid\) \Description Destroys a thread. Without an argument, destroys the current thread. \Command{threadstop} \Abbreviated{ts} \Example\(threadstop $my_thread\) \Description Stops a thread. Without an argument, stops the current thread. Only a running thread can be stopped. When a thread is stopped, it cannot run and events for it will be queued. The only to resume a stopped thread is to issue the \(threadcont\) command. \Command{threadunfreeze} \Abbreviated{tu} \Description Unfreezes the given thread. This is useful for debugging. The user may interrupt the system, do something generating an event, inspect the state of the (presumably frozen) thread that is supposed to handle the event, and then manually unfreeze the thread while leaving other threads frozen, to prevent side effects. The user can then list the threads and find out which threads have events, and dump the relevant threads to find out what's going on. \Command{trace} \Abbreviated{t} \Example\(trace 10\) \Description Steps through the target program until the current source line number changes. If an argument is given, it is used as a repeat count. If line number information is not available, it pretends the line number changes each instruction. \Command{traceforward} \Abbreviated{tf} \Description Steps through the target program until the current source line number increases --- that is, it stops when \(CS:IP\) reaches a point in the same file but a larger line number. This is useful at the end of loops, to continue until the loop ends. However, it is fooled if the loop calls a procedure which is later in the same file. Its argument, if supplied, is used as a repeat count. \Command{traceinstruction} \Abbreviated{ti} \Description Steps forward a single assembly language instruction. If an argument is given, it is used as a repeat count. \Command{traceprocedure} \Abbreviated{tp} \Description Steps forward until a procedure call or software interrupt call is found. Then it sets a breakpoint at the point where the call returns, and blocks. \Command{unassemble} \Abbreviated{u} \Example\(u _main\) \Description Unassembles code at the given address \Command{unix} \Description Issue a UNIX system call. Several system calls are supported, and are described individually below. \Command{unpack} \Abbreviated{un} \Example\(unpack ds:bx, "CSL", $foo, $bar, $baz\) \Example\(unpack $packet, "nN", $code, $address\) \Description Performs the reverse of \(pack\). It has two forms. The first form takes a memory address, a \(pack\) control string, and arguments (which must be lvalues). The bytes at the address are read from memory, interpreted according to the letters in the control string, and stored in the corresponding arguments. The return value is the address just following the last byte read by \(unpack\). Memory read events are generated for locations read. The second form takes a string as its first argument. It unpacks the bytes in the string, rather than bytes in target memory. It returns the number of bytes used, which is also the index into the string just past the last byte used. \Command{up} \Description Performs the reverse of \(down\). It climbs up one stack frame, to the current frame's caller, and displays the frame. \Command{varlist} \Abbreviated{vl} \Description Lists all global variables, and displays their values. \Command{warnings} \Abbreviated{w} \Description Lists the supported warnings, and whether they are enabled or disabled for the current machine. \Command{warncontrol} \Abbreviated{wc} \Description Toggles whether or not the user is warned when the current machine undergoes a control transfer (a procedure call or return, and interrupt call or return, or a long jump.) This usually produces lots and lots of warnings, but used judiciously can be helpful to pinpoint where code runs foul. If an argument is specified, it is interpreted as a boolean; a true value enables the warning, and a false value disables it. \Command{warndma} \Abbreviated{wd} \Description Toggles whether or not the user is warned when the current machine's DMA controller performs a DMA operation. If an argument is specified, it is interpreted as a boolean; a true value enables the warning, and a false value disables it. \Command{warnevents} \Abbreviated{we} \Description Toggles whether or not the user is warned when a thread is sent an event. If an argument is specified, it is interpreted as a boolean; a true value enables the warning, and a false value disables it. This warning is especially useful for debugging threads. Trace complete events are never displayed, even if this warning is enabled, because they are considered completely uninteresting. \Command{warninterrupts} \Abbreviated{wi} \Description Toggles whether or not the user is warned when hardware interrupts are requested and serviced. Like \(warncontrol\), it accepts an optional boolean argument explicitly enabling or disabling the warning. \Command{when} \Example\(when memorywrite(_myvar) { print "YOW!"; }\) \Description Takes an event specification list followed by a block of commands in curly braces. It forks a thread (returning its thread ID) that is blocked until an event matching the specification is received. At that point, the commands in the braces are executed and the thread exits. The command \code when 0:0.100000 { print "It's time"; } \code \noindent is actually syntactic sugar for \code fork { blockuntil 0:0.100000; print "It's time"; } \code \Command{whenever} \Example\(whenever memorywrite(_myvar) { print "YOW!"; }\) \Description Takes an event specification list followed by a block of commands in curly braces. It forks a thread (returning its thread ID) that is in an infinite loop, blocking until an event matching the specification is received. At that point, the commands in the braces are executed and the thread blocks again. The command \code whenever _my_proc { print "_my_proc called!"; } \code \noindent is actually syntactic sugar for \code fork { while (1) { blockuntil _my_proc; print "_my_proc called!"; } } \code Note that any expressions you put in the event specification list are evaluated in the context of the new thread, and are re-evaluated every time around the loop. Thus, code like \code whenever .+2 { ... } \code \noindent may not do what you expect (the breakpoint will be set in a different place each time around the loop.) \Command{<} \Example\(< myfile.sot\) \Description This is not actually a command operator. It directs SOTEST to read commands from the named file in the spirit of \(#include\). Note that the filename is a literal, not a string expression; the name is not in quotes, and string operators are not allowed. \leftskip=0pt \section{Events, Event Specifications, Event Predicates} SOTEST supports 16 event types. Of these, five are used internally and are never seen by the user or SOTL code. There are 11 others that threads (or the user) may subscribe to, receive, display, and act on. These visible event types are target memory read, memory write, port read, port write, breakpoint, breaktime, idle machine, interthread message receive, thread exit, UNIX file descriptor ready, and UNIX message queue readable. The internal event types are command start, fork, target call return, trace complete, and interrupts allowed. The user tells SOTEST what events are interesting by providing event specifications. The \(break\) operator subscribes the user to the given event specifications; when an event matching one of the specifications is received, the user is notified and simulation is suspended. The \(blockuntil\) operator deletes the thread's old subscriptions, subscribes the thread to the given event specifications, and blocks the thread; when an event is received, the thread unblocks. The \(go\) operator is like \(blockuntil\), but is meant for use by the foreground thread; in addition to subscribing the thread to the given specifications and blocking the thread, it unfreezes all frozen threads and prints machine state when an event is received. When \(blockuntil\) (or \(go\)) returns, there is an event waiting for the thread. The thread can find out what sort of event it is with event predicates. Event predicates are actually like command operators, and can be used inside expressions just like command operators. There is one event predicate per event type. Each event predicate returns true if the event is of the given type, and false if it's not. If the event is of the given type, details of the event will be written into the arguments given to the event predicate. \subsection{Event Types} The event types listed above are described here. \leftskip=0.5in \Type{memoryread} \Details{address, size} \Meaning This event is generated whenever a machine reads a memory location. It is also generated by certain command operators, such as \(memoryfetch\), as described above. The address of the memory location read and the size of the read (1 for a byte read, 2 for a word read) are included in a \(memoryread\) event. \Type{memorywrite} \Details{address, value, size} \Meaning This event is generated whenever a machine writes to target memory. It is also generated by certain command operators, such as \(enterbyte\), as described above. The address of the memory location written, the value written there, and the size of the write (1 for a byte write, 2 for a word write) are included in a \(memorywrite\) event. \Type{portread} \Details{port, size} \Meaning This event is generated whenever a machine reads a target I/O port. It is also generated by certain command operators, such as \(inbyte\), as described above. The address of the port read and the size of the read (1 for a byte read, 2 for a word read) are included in a \(portread\) event. \Type{portwrite} \Details{port, value, size} \Meaning This event is generated whenever a machine writes a target I/O port. It is also generated by certain command operators, such as \(outbyte\), as described above. The address of the port written and the size of the write (1 for a byte write, 2 for a word write) are included in a \(portwrite\) event. \Type{breakpoint} \Details{address} \Meaning This event is generated when the machine starts to execute an instruction. The current value of \(CS:IP\) is included in the event. \Type{breaktime} \Details{time} \Meaning This event is generated when the machine's clock goes past a certain value. The current value of the clock is included in the event. \Type{idlemachine} \Details{machine} \Meaning This event is generated when a machine is declared idle by the \(machineidle\) command. The machine declared idle is included in the event. \Type{messagereceive} \Details{sender, message} \Meaning This event is generated when a thread sends another thread a message. The thread ID of the sender, and the contents of the message, are included in the event. \Type{threadexit} \Details{thread ID, exit value} \Meaning This event is generated when a thread exits. The thread's ID and the result of the thread's last evaluation are included in this event. \Type{filedescriptor} \Details{unix file descriptor} \Meaning This event is generated when a file descriptor is ``ready.'' For a file descriptor receiving connections with unix \(listen\)(), this means a connection has been initiated. For other file descriptors, it means the descriptor is readable. There is no way to be notified when a descriptor is writable; an attempt to write a full pipe causes then entire SOTEST process to block. \Type{messagequeue} \Details{unix message queue ID} \Meaning This event is generated when a message queue has messages in it. The message queue ID is included in the event. \Type{command {\it (internal event type)}} \Details{none} \Meaning This event is sent to a thread when it is forked as a user command, causing it to assume the role of the foreground thread. It is never visible to the user. \Type{fork {\it (internal event type)}} \Details{parent thread ID} \Meaning This event is sent to a thread when it is forked from another thread. \Type{callreturn {\it (internal event type)}} \Details{call return value} \Meaning This event is generated when a target procedure call (initiated by the \(call\) command) returns. \(call\) causes the thread to block; this event is sent to make it unblock. The return value of the target call is included in the event, and becomes the return value of the \(call\) command. This event is never visible to the user. \Type{tracecomplete {\it (internal event type)}} \Details{none} \Meaning This event is generated when a target single-step (trace instruction) operation completes. All trace commands actually cause the thread to block momentarily; this event unblocks the thread. It is never visible to the user. \Type{interruptsallowed {\it (internal event type)}} \Details{none} \Meaning This event is generated when the target goes into a state in which hardware-requested interrupts can be serviced, {\it i.e.,} the interrupt flag is set. It is used only by the \(interrupt\) command operator above. \leftskip=0pt \subsection{Event Specifications} Event specifications can be dwords, time values, file descriptors, or message queue ID's. A dword is a specifier for a breakpoint; a \(breakpoint\) event will be received when execution reaches the address indicated by the dword. A time value is a specifier for a breaktime; a \(breaktime\) event will be received when the clock reaches the given time value. A file descriptor is a specifier for \(filedescriptor\) events involving the given file descriptor; when the given file descriptor becomes readable or has a connection requested, an event will be received. A message queue ID is a specifier for \(messagequeue\) events; a \(messagequeue\) event will be generated when a message is waiting in the given event queue. \leftskip=0.5in \Example\(blockuntil _my_func, 0:0.12345, $descriptor\) \Meaning The current thread will block until either \(CS:IP\) reaches \(_my_func\), the clock reaches 12345 ticks, or the file descriptor stored in \($descriptor\) is ready. \leftskip=0in \subsection{Event Specification Constructors} Only specifiers for those four event types (\(breakpoint\), \(breaktime\), \(filedescriptor\), and \(messagequeue\)) can be created with SOTL objects. Specifiers for all user-visible event types can be created by event specification constructors. There is one such constructor for each user-visible event type. In each case the constructor has the same name as the event type. Event specification constructors are allowed only immediately following \(break\), \(blockuntil\), or \(go\). Event specifications are not themselves SOTL objects, and cannot be stored in variables or passed as arguments to SOTL functions. \leftskip=0.5in \Constructor{memoryread} \Example\(blockuntil memoryread (_my_data, _my_data + 20)\) \Description Constructs a specifier for memory read events from addresses from \(_my_data\) to \(_my_data + 19\), inclusive. If the constructor is given only one argument, a specifier for memory reads from that address alone is constructed; thus, \(memoryread(x)\) is equivalent to \(memoryread(x, x+1)\). \Constructor{memorywrite} \Example\(go memorywrite (_my_data, my_data + 20)\) \Description Like \(memoryread\), but for memory write events \Constructor{portread} \Example\(break portread (0x3f0, 0x3f8)\) \Description Like \(memorywrite\), but for port read events \Constructor{portwrite} \Example\(blockuntil portwrite (0x3f0, 0x3f8)\) \Description Like \(memorywrite\), but for port write events \Constructor{breakpoint} \Example\(break breakpoint (_my_func)\) \Description Constructs a specifier for breakpoint events at the given address. Note that breakpoint event specifiers can be constructed more simply by simply providing the address; this syntax is provided only for uniformity. Thus, the following forms are equivalent: \code blockuntil _my_func blockuntil breakpoint(my_func) \code \Constructor{breaktime} \Example\(go breaktime (01:26.00000000)\) \Description Like \(breakpoint\), but for \(breaktime\) events. It is redundant in the same sense that \(breakpoint\) is. \Constructor{idlemachine} \Example\(blockuntil idlemachine (my_machine)\) \Description Constructs a specifier for \(idlemachine\) events for the given machine. When the given machine is declared idle, an \(idlemachine\) event will be received. Note that machines could be allowed as event specifiers, making this event specification constructor redundant, but currently they are not. \Constructor{messagereceive} \Example\(break messagereceive()\) \Description Constructs a specifier for \(messagereceive\) events. When the current thread is sent a message by any other thread, a \(messagereceive\) event will be received. The \(messagereceive\) event, of course, contains the mesasge itself. \Constructor{threadexit} \Example\(blockuntil threadexit($my_child)\) \Description Constructs a specifier for \(threadexit\) events. When the thread with the given ID exits, a \(threadexit\) event will be received, containing the exited thread's ID and the result of its final evaluation. \Constructor{filedescriptor} \Example\(go filedescriptor ($descriptor)\) \Description Like breakpoint, but for \(filedescriptor\) events. It is redundant in the same sense that \(breakpoint\) is. \Constructor{messagequeue} \Example\(blockuntil messagequeue ($message_queue_ID)\) \Description Like breakpoint, but for \(messagequeue\) events. It is redundant in the same sense that \(breakpoint\) is. \leftskip=0pt \subsection{Event Predicates} When a thread unblocks after receiving an event, it needs some way to find out what event was received and what its details were. Event predicates provide this mechanism. Event predicates are command operators that return true if the last event received matches the pedicate, and false otherwise. If the event matches, the details of the event are written into the event predicate's arguments. Like event specification constructors, there is one event predicate per user-visible event type. Note that event predicates can not be used anywhere in the arguments to \(break\), \(blockuntil\), or \(go\), because they will be interpreted as event specification constructors. \leftskip=0.5in \Predicate{memoryread} \Example\(if memoryread($address, $size)) { ... }\) \Description Tests if the last event received was a \(memoryread\) event. If so, it returns true and fills in its arguments with the address and size read. The size is 1 for a byte read, or 2 for a word read. \Predicate{memorywrite} \Example\(if memorywrite($address, $value, $size) { ... }\) \Description Tests if the last event received was a \(memorywrite\) event. If so, it returns true and fills in its arguments with the address, value, and size written. The size is 1 for a byte write, or 2 for a word write. \Predicate{portread} \Example\(if portread($port, $size)) { ... }\) \Description Tests if the last event received was a \(portread\) event. If so, it returns true and fills in its arguments with the port and size read. The size is 1 for a byte read, or 2 for a word read. \Predicate{portwrite} \Example\(if portwrite($port, $value, $size) { ... }\) \Description Tests if the last event received was a \(portwrite\) event. If so, it returns true and fills in its arguments with the port, value, and size written. The size is 1 for a byte write, or 2 for a word write. \Predicate{breakpoint} \Example\(if breakpoint($where) { ... }\) \Description Tests if the last event received was a \(breakpoint\) event. If so, the code location at which the breakpoint was hit is written into this operator's only argument. \Predicate{breaktime} \Example\(if breaktime($when) { ... }\) \Description Tests if the last event received was a \(breaktime\) event. If so, the value of the clock when the breaktime event was generated is written into this operator's only argument. \Predicate{idlemachine} \Example\(if idlemachine($which_machine) { ... }\) \Description Tests if the last event received was an \(idlemachine\) event. If so, the machine that went idle is written into this operator's only argument. \Predicate{messagereceive} \Example\(if messagereceive ($from_whom, $message) { ... }\) \Description Tests if the last event received was a \(messagereceive\) event. If so, the thread ID of the sender and the message itself are written into this operator's arguments. \Predicate{threadexit} \Example\(if threadexit ($who_died, $exit_value) { ... }\) \Description Tests if the last event received was a \(threadexit\) event. If so, the thread ID of the thread that exited and the result of its final evaluation are written into this operator's arguments. \Predicate{filedescriptor} \Example\(if filedescriptor ($mydesc) { ... }\) \Description Tests if the last event received was a \(filedescriptor\) event. If so, the file descriptor that became ready is written into this operator's argument. \Predicate{messagequeue} \Example\(if messagequeue ($thequeue) { ... }\) \Description Tests if the last event received was a \(messagequeue\) event. If so, the message queue ID that has messages waiting is written into this operator's argument. \leftskip=0pt \section{UNIX System Calls} As mentioned above, several Unix system calls can be accessed via the \(unix\) command operator. They are described below. \leftskip=0.5in \SystemCall{unix accept ()} \Example\($new_connection = unix accept ($fd)\) \Description Performs the \(accept\)(2) system call. It returns a new file descriptor, or \(nil\) in case of error. \SystemCall{unix bind ()} \Example\(unix bind ($fd, $sockaddr)\) \Description Performs the \(bind\)(2) system call. The second argument is a string specifying the socket address; the length of the address is the length of the string. It returns the result of \(bind\)(2). \SystemCall{unix connect ()} \Example\(unix connect ($fd, $sockaddr)\) \Description Performs the \(connect\)(2) system call. The second argument is a string specifying the socket address; the length of the address is the length of the string. It returns the result of \(connect\)(2). \SystemCall{unix errno ()} \Example\($errcode = unix errno()\) \Description Returns the current value of \(errno\) as a dword. \SystemCall{unix getenv ()} \Example\($homedir = unix getenv("HOME")\) \Description Returns the value of the named environment variable as a string, or \(nil\) if the variable is not set. \SystemCall{unix listen ()} \Example\(unix listen ($fd, 5)\) \Description Performs the \(listen\)(2) system call. \SystemCall{unix mkfifo ()} \Example\(unix mkfifo ("/tmp/my_named_pipe")\) \Description Performs the \(mkfifo\)(2) system call, using mode \(0666\). \SystemCall{unix msgget ()} \Example\($queue = unix msgget ($key)\) \Description Performs the \(msgget\)(2) system call. It passes the key you provide (a dword), and \(IPC_CREAT | 0777\) for flags. Returns a message queue, or \(nil\) if it fails. \SystemCall{unix msgsnd ()} \Example\(unix msgsnd ($queue, pack("H", 200) . "hello")\) \Description Sends a message to the given queue. The first argument is a message queue, as returned by \(msgget\). The second argument is a string representing a \(struct msgbuf\); according to UNIX definitions (see \(msgsnd\)(2)), it should be a host long (indicating the message type) followed by data. An optional third argument specifies the length of the data portion of the message. For example, \code $type = pack("H", 300); unix msgsnd ($queue, $type . "Test", 1) \code \noindent sends a message of type 300, one character in length, with that character being a `\(T\)'. \SystemCall{unix msgrcv ()} \Example\(unix msgrcv ($queue, $message, 1024, 200);\) \Description Receives a message from the given queue. The first argument is the message queue, as returned by \(msgget\). The second argument will have the message stored into it. The third is the maximum size that will be received. The fourth argument specifies the type of message that may be received, as in \(msgrcv\)(2). 0 means any type. \SystemCall{unix open ()} \Example\($descriptor = unix open ("/tmp/myfile", 1, 0x3ff)\) \Description Opens the given file and returns a descriptor if it succeeds, or \(nil\) otherwise. The second and third arguments are the flags and mode words, and default to 0. \SystemCall{unix read ()} \Example\(unix read ($descriptor, $result, $size)\) \Description Reads from a file descriptor. At most \($size\) bytes are read, and are stored in the string \($result\). If EOF is hit, 0 is returned; if there is an error, -1 is returned; and if the read is successful, the number of bytes read is returned. \SystemCall{unix recv ()} \Example\(unix recv ($descriptor, $msg, 1024)\) \Description Calls the unix \(recv\)(2) system call and returns its result. The data received is stored as a string in the second argument; the third argument is the maximum number of bytes to receive. \SystemCall{unix recvfrom ()} \Example\(unix recv ($descriptor, $msg, 1024, $sockaddr)\) \Description Calls the unix \(recvfrom\)(2) system call and returns its result. The data received is stored as a string in the second argument; the third argument is the maximum number of bytes to receive. The fourth is filled in with the address from which the message was received. \SystemCall{unix semctl ()} \Example\(unix semctl ($semid, 0, $SETALL, pack("hhh", 1, 2, 3))\) \Description Calls the unix \(semctl\)(2) system call and returns its result. The arguments are the semaphore set ID returned by \(semget\), the semaphore number, a command, and an argument. The constants used as commands are not defined for you; see \(\). If you pass \(GETALL\) or \(IPC_STAT\), the fourth argument must be a variable which, after successful completion of the \(semctl\)(2) call, will hold the \(semval\)'s or \(struct semid_ds\) which the system call fills in. If you pass \(SETALL\) or \(IPC_SET\), the fourth argument must be a string whose bytes make up an array of \(semval\)'s or a \(struct semid_ds\); the \(pack\) operator is a good way to generate such a string. \SystemCall{unix semget ()} \Example\(unix semget (1000, 10);\) \Description Calls the unix \(semget\)(2) system call and returns its result. The arguments are the key for the semaphore set and the number of semaphores in the set. A flags value of \(IPC_CREATE | 0777\) is passed as \(semget\)'s third argument. \SystemCall{unix semop ()} \Example\(unix semop ($semid, 0, -2, 0, 1, 3, 0);\) \Description Calls the unix \(semop\)(2) system call and returns its result. The first argument is a semaphore set ID. The remaining arguments are grouped into sets of three. Each set of three arguments makes up a semaphore operation, corresponding to the fields of \(struct sembuf\). Thus, the above call subtracts 2 from semaphore 0 of the given set, and adds three to semaphore 1 of the set. (In each operation, a flags value of 0 is used.) \SystemCall{unix send ()} \Example\(unix send ($descriptor, "Hello")\) \Description Calls the unix \(send\)(2) system call and returns its result. The third argument is the number of bytes to send, and defaults to the length of the string. \SystemCall{unix sendto ()} \Example\(unix sendto ($descriptor, "Hello", $sockaddr)\) \Description Calls the unix \(sendto\)(2) system call and returns its result. The final argument is the destination address. If four arguments are given, the third argument is the number of bytes to send, and defaults to the length of the string. \SystemCall{unix socket ()} \Example\($descriptor = unix socket (PF_UNIX, SOCK_STREAM);\) \Description Calls the unix \(socket\)(2) system call. You may use the symbolic constants \(PF_UNIX\) or \(PF_INET\) as the protocol family, and \(SOCK_STREAM\) or \(SOCK_DGRAM\) as the type. You may also pass a dword for either argument. The third argument given to the unix \(socket()\) call is always zero. In case of error, \(nil\) is returned; otherwise, the file descriptor associated with the new socket is returned. \SystemCall{unix sprintf ()} \Example\($now = unix sprintf ("%03d %s", 10, "hello")\) \Description Returns the output of the \(sprintf\) library function. The first argument must be a control string as described in \(sprintf\)(3). The remaining arguments are passed to \(sprintf\). If the argument is a string, a pointer to the string's contents (which will be null-terminated) is passed; otherwise, the argument is promoted to a dword and passed like a long. {\bf Warning:} if you do evil things, like \code unix sprintf ("%s", 100); \code \noindent you will lose; SOTEST will dump core and it's your fault! (So there.) \SystemCall{unix time ()} \Example\($now = unix time ()\) \Description Returns the number of seconds since midnight on the first of January, 1970, in Greenwich Mean Time. \SystemCall{unix unlink ()} \Example\(unix unlink ("/tmp/myfile")\) \Description Unlinks the given file. \SystemCall{unix write ()} \Example\(unix write ($descriptor, $data, $size)\) \Description Writes bytes from the given string. \($size\) is the number of bytes, which is limited by (and defaults to) the length of the string. Returns the number of bytes successfully written, or -1 for error. \leftskip=0pt