---------------------------------------------------------------------- SOTEST USER'S GUIDE ---------------------------------------------------------------------- Written by Ken Duda for version 0.9932 ----------- Assumptions ----------- This guide assumes a basic understanding of embedded system components (things like "target", "firmware", "RAM", "microprocessor", and "loadware") and a basic understanding of UNIX (things like shells, processes, files, and the path). You will get more out of SOTEST if you are familiar with the 80186 at an assembly level, but such familiarity is not required. ----------------------- What is SOTEST, Anyway? ----------------------- SOTEST is a combination of a microprocessor simulator, symbolic debugger, and hardware modeling language. It is meant to be useful as a workstation-based debugging environment, unit-test environment, and regression test environment for embedded system firmware and loadware. Currently it simulates the 80186 and provides debugging facilities similar to dbxtool. --------------- Starting SOTEST --------------- Sotest is in /usr/local/fwlwtools/sun4/bin on Sparc's (sun3/bin on Sun-3's.) Put /usr/local/fwlwtools/`bin/arch`/bin in your path. Then start it with % xsotest After a little while, a window will come up. The top portion of the window is for viewing source files. The lower portion is for interacting with the SOTEST system. In this lower window you should see: ------------- SOTEST version x.xxxx ----------- Mach1: _ There is also an emacs interface to SOTEST, which I recommend over the X interface if you're comfortable with emacs. See the document "How to Use the Emacs Interface to SOTEST" for more information. --------------- Getting Started --------------- Before you can do anything useful with SOTEST, you must have the following components: o target loadware (or firmware) bind in an Intel absolute object module (ABS) file o Programs for simulating your project's external hardware components written in SOTEST hardware modeling language (SOTL). By external hardware components, I mean every piece of target hardware (besides the processor and its RAM and ROM) and every piece of hardware the target communicates with. See your project's SOTEST administrator to find out where these things are located. You may need to type in a few commands to load your project's loadware, firmware, and/or SOTL external hardware component simulation program. Your project's SOTEST administrator should be able to tell you what commands to type to do this. ------------- Using XSOTEST ------------- You can do quite a bit of debugging with XSOTEST without using only the mouse. Click on "go" to run the target software; click on "Interrupt" to stop it. When the target software is interrupted, you can use "trace" to single-step, "backtrace" to print a stack dump, and "up" and "down" to walk up and down the stack. You should see source files in the upper XSOTEST window as you try these commands. You can also set breakpoints and print out program variables. To set a breakpoint, highlight part of a line of code and click on "break". An indication that a breakpoint is set should appear in the source window. You can delete the breakpoint by selecting the code line and clicking on "breakdelete". To print a variable (or expression), highlight the variable and click on "print". ------------------------ The SOTEST Command Line ------------------------ Most XSOTEST buttons are actually abbreviations for SOTEST commands, which can be typed at the SOTEST command line. To type commands directly to SOTEST, first click on the lower region of the XSOTEST window. The cursor should become visible. At this point, you can type commands; when you press return, they'll be sent to SOTEST. For example, if you type "r" and hit return, you should see the state of the microprocessor registers. In addition, you can press control-C to interrupt SOTEST. The SOTEST command line language is actually SOTL, the same language as the SOTEST hardware modeling language. You can refer to the document "SOTEST REFERENCE MANUAL" for a complete description of SOTL. However, listed here are some common commands you might find useful. Note that many commands are lengthy, but can be abbreviated. Command: < Example: < myfile.sot Description: directs SOTEST to read commands from the named file in the spirit of #include. Note that the filename is a literal, not in quotes or brackets. Command: break Abbreviated: b Example: break _main, myfile:200, 1234h:5678h Description: sets breakpoints at the given addresses. Addresses can be given in many forms: the name of a procedure, a location in the source code (module:line), or an actual literal address (segment:offset). There are actually several other ways; see the reference manual for more information. 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: 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 begins execution. 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: 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: 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. 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. Command: unassemble Abbreviated: u Example: u _main Description: unassembles code at the given address. This is only useful if you know 80186 assembly language.