Table of contents Overview: An overview of the tkisem program Using help: A bit about using help About Tcl errors: They shouldn't happen, but... The windows: A summary of the windows provided by tkisem Main window: A description of the main window Register window: The second most important window Symbol window: Used to view user and supervisor symbols Breakpoint window: Used to set, clear, and view breakpoints Text display window: Used to view your program Data display window: Used to view the data memory Breakpoints: A quick summary of using and setting breakpoints The devices: A brief overview for each of the devices The rom code: A brief description of the tkisem rom code ISEM - Instructional Sparc EMulator and tkisem Copyright (C) 1993, 1994, 1995, 1996 Department of Computer Science, The University of New Mexico Overview Tkisem is Tcl/Tk-based wrapper around the ISEM program. ISEM is an instructional SPARC emulator for version 8 of the SPARC definition. ISEM and tkisem were developed by a collection of students and faculty in the Computer Science Department at the University of New Mexico. If you have any problems installing or using this program, send mail to isem@cs.unm.edu. Tkisem provides a full emulation of the SPARC integer and floating point units along with a small collection of devices. The collection of devices includes a console device, an interval timer, and a UART. For more information see The devices. When you start tkisem, it starts by loading and running a supervisor program, called tkisem_rom. This program initializes the devices, installs software handlers for the devices, and installs handlers for various traps, faults, and exceptions. For more information see the rom code. Using help At present, there is no serious, genuine, help for tkisem. Instead, there is this little file. It'll have to do for now. All the help text is loaded into tkisem the first time any help is requested and remains loaded thereafter for the duration of the program's running. Cross references you see something like, say, Overview, or Table of contents, you can click left on it and jump to the corresponding label in the help text. Help buttons In addition, the Help buttons on the various windows in tkisem operate as if you had clicked on a particular help topic. Disclaimer Note: this help file is still under construction, so there may be cross-references to things that haven't been written yet. Clicking on such an undefined cross-reference (say Foo (try it!)) leaves you where you are in the help file and puts a "Can't find help label 'Foo'" message in the message line. About Tcl errors It is possible to do something that causes a window to pop up with the label 'Error in Tcl Script'. This window will contain an error message, and provide two buttons, one saying 'OK' and one saying 'See Stack Trace'. In an ideal world, you shouldn't get this kind of message. It means is that tkisem isn't handling an error the way it should. Hopefully, you'll be able to figure out what happened and find a way to continue. If you find a systematic way to generate one of these errors, send mail to isem@cs.unm.edu explaining how to create the error. The windows Tkisem provides several windows for viewing the state of the emulated processor and devices and for controlling the execution of instructions. In this section, we give brief overviews for these windows and offer suggestions on which windows that you should become familiar with. The Main window is the window that you get when you start tkisem. This window lets you load and execute programs. It also includes the console input and output displays. This is by far the most important window in tkisem. You should become familiar with this window as soon as you start to use tkisem. The Register window is the second most important window. This window displays the values of the registers defined in the integer unit of the SPARC. It also shows the next instruction to be executed and provides a register edit region so you can change the values in the registers. You also need to become familiar with this window as soon as you start to use tkisem. The Symbol window displays the symbols (labels) defined by the program loaded in user or supervisor memory. This window provides useful information, but is not needed very often. The Breakpoint window can be used to set, clear, and view breakpoints. Like the symbol window, this window provides useful information, but it is not needed very often. Moreover, the information displayed in this window is presented in a better format in the text display window (unless you have set a lot of breakpoints and want to review them). The Text display window is used to view your program. This window identifies the instructions that are associated with breakpoints and the instruction that is pointer to by the program counter. As soon as you have become familiar with the main window and the register window, you should become familiar with this window. The Data display window can be used to view the data memory for a program. This is useful if you want to see how the values stored in memory are changed as a result of executing instructions. This window can be very useful when you are debugging and/or testing programs. The Timer window displays information related to the interval timer. If you write a program that uses this device, you will want to become familiar with this window. The UART window displays information related to the UART. If you write a program that uses this device, you will want to become familiar with this window. Main window The main window is the window you get when you start tkisem. Our discussion of the main window is broken into two parts: Main window structure -- discussing the structure of the window, and Main window activities -- discussing the activities that can be performed using the main window Main window structure From top to bottom, in sections, the main window contains: a Menu bar, a Processor state, a Load/run section, a Message line, a Console output window, and a Console input window. Menu bar. The menu bar has eight pull down menus: File, Registers, Symbols, Breakpoints, Memory, Devices, Options, and Help. File menu. Currently, the file menu can only be used to Quit the program. Registers menu. The register menu is be used to Display the Register window. Symbols menu. The symbols menu brings up the user and/or super Symbol window. Breakpoints menu The breakpoints menu brings up the user and/or supervisor Breakpoint window. Memory menu. The memory menu brings up the user and/or supervisor Data display window and/or the Text display window. The text display window is the place to see your code while it's running! Devices menu. The devices menu brings up the Timer window and/or the UART window. Options menu. Currently, the options menu lets you select how the register names are displayed. You can have register names displayed using standard notation (%r), or register window notation (%g, %o, %l, and %i). Help menu. The help menu brings up this help window. Processor state The processor state portion of the main window summarizes the current state of the emulated processor. This part of the display is broken into five regions. From left to right they are: the processor state, the processor mode, the step and display toggles, the instruction and memory reference counts, and the file names. The processor state is indicated by a box labeled Proc State. This box should normally say execute (with a light green background on color displays). If you manage to halt the (emulated) processor, Proc State will say error with a red background. The processor mode is indicated by a box labeled Proc Mode. This box is super or user depending on whether the processor is currently in supervisor mode or user mode. It displays the same information as the S bit in the PSR which can be seen in the Register window. The step and display toggles let you control single stepping and the display updates. In single stepping, tkisem will stop after each instruction is executed so you can examine the state of the processor, registers, or memory. Each processor mode (supervisor and user) has a toggle button labeled Step. If the Step toggle is set for one of the modes, tkisem will single step instructions when the processor is in this mode. Display updates take a moderately long time. As such, tkisem lets you control if display is updated. Like single stepping, display updating is associated with the processor mode. Display updating is controlled by the Display buttons, one for each mode. If you set single stepping, you will automatically get display updating for that mode. You can also set display updating without setting single stepping. This lets you "watch" the program as it runs. At startup, User Step and User Display are set, since most of the time you will be programming (and debugging) programs written for user mode. If you write supervisor code (see the rom code), you may want to control single stepping and display updating for supervisor mode. The instruction and memory reference counts are next to the step and display toggles. This region consists of four counters, a pair of counters for each of the processor modes. The first (leftmost) counter tracks the number instructions that have been executed in this mode. The second counts the number of memory references in this mode. All four counters are cleared whenever you load a file into the user or supervisor memory. Finally, the file name section consists of two boxes labeled User File and Super File. These boxes give the names of the executable files last loaded into the user memory and supervisor memory of tkisem. Load/run section The next section of the main window contains a pair of radio buttons, User and Super, two command buttons Load and Run, a text entry area, and Display frequency slider. The User and Super radio buttons select whether the Load button loads into user memory or supervisor memory. When tkisem is first run, a special file tkisem_rom is loaded into supervisor memory. After initialization is complete, the load mode is switched to User to be ready to load your program. The Display frequency slider determines how often the information in the various windows is updated while the emulator is running. It is initialized to 1, meaning that the windows are updated after every instruction is executed. Setting it to a higher value reduces the frequency of display updates, but allows the emulation to run more quickly. Message line The message line is used by tkisem to display status messages. As an example, tkisem displays breakpoint messages in the message line. Console output The console output region displays text generated by running code. After the emulator is first started, and the supervisor initialization code has run, the message Default trap handlers installed is sent to the console output. Console input The console input region displays characters that can be read by the running program. You should treat the console input as a sequential, append-only character device. Using the cursor, you can insert characters anywhere you like. However, if you insert characters anywhere other than the end of text, things may not work as expected. Characters typed in the console input region are not passed to the running program until you type a newline (carriage return). Main window activities There are two primary activities that you will perform using the main window: loading a program and running a program after it's been loaded. Loading a program. To load a user program, take the following steps: 1) Make certain ~eg[User] is checked off; 2) Enter the name of the file to load. (If you didn't use a -o switch when you linked your program with isem-ld, the name of the program will be a.out.) 3) Click the Load button. Running a program. Once you've loaded a program into user or supervisor memory, you can start it running by clicking the Run button. The exact behavior of the emulator when you click the Run button depends on the settings of the user and supervisor step and display check boxes in the Processor state. If you set Step toggle, pressing the Run button will execute a single instruction. Otherwise, pressing the Run button will execute many instructions. While the emulator is executing instructions, the Run button changes into a Stop button and can be used to stop execution. (See also Breakpoints). Register window The register window is where all the internal processor state, as well as the next instruction to be executed, is displayed. You probably want to have the register window up visible most of the time. There will be more help here one of these days maybe. Symbol window There are two symbol windows, one for user symbols and another for supervisor symbols. The display portion of the symbol window consists of two columns. The first column show the name of the symbol, the second shows the value and region (abs, bss, data, or text) associated with the symbol. By default, the symbols are sorted by their names. By clicking on the Value radio button, you can display the symbols sorted by their values within each region. (If two or more symbols are associated with the same value, only one of the symbols will be displayed.) To return to the display where symbols are sorted by name, click on the Name radio button. Breakpoint window There are two breakpoint windows, one for user breakpoints and another for supervisor breakpoints. The breakpoint windows display breakpoints in two columns. The first column shows the label of the instruction associated with the breakpoint (if the instruction has a label). The second column shows the address of the instruction associated with the breakpoint. The Clear All button clears all of the breakpoints. The Delete and Add buttons can be used to delete or add individual breakpoints. To add or delete a breakpoint, type the address or label of the instruction in the entry box to the right of the Add button and click on the Add or Delete button. Note: the text display window provides a better interface for adding and deleting individual breakpoints (see Text display window). Text display window The text display windows (one for user memory and another for supervisor memory) display the instructions in a program. The window has a display region and an update region. The update region is at the bottom of the window and consists of a button and two entry boxes. The button is labeled Update, the entry boxes are labeled Start and End. Tkisem initializes these with its best guess of the program start and program end. You can change these values by typing instruction addresses or labels in these entry boxes. Clicking the Update button updates the instructions shown in the text display window. Displaying the text takes a bit of time, so the instructions for your program are not shown when you first pop up the text display window. To see the instructions, click on the Update button. The display part of the window uses five columns to show the instructions of a program. The first column indicates if the instruction is identified as a breakpoint (see Breakpoints). This column also indicates the next instruction to be executed (i.e., the value of the PC). If an instruction is identified as a breakpoint, the symbol 'B' appears in the first column. If the instruction is the next instruction to be executed, the symbol '>' is displayed in the first column. The second column displays the address of the instruction. If you double click on an address, tkisem toggles whether the instruction is identified as a breakpoint. The third, forth, and fifth columns display the label, operation, and operands for the instruction. The Update button can be used to update the range of instructions displayed in the text display window. Tkisem tries to guess where your program starts and ends. Usually, tkisem is pretty good about guessing; however, it is possible that tkisem will not guess correctly. To change the range of instructions displayed, you can set the Start and End entry boxes and click on the Update button. Data display window The data display windows are similar to the text display windows: there are two data display windows, one for user memory and one for supervisor memory; data display windows have a display region and an update region; and the data values are not initially displayed. The update region of the data display region operates just like the update region of the text display window. You can enter addresses or labels in the Start and End entry boxes and click on the Update button to update the region of memory displayed. Words of data memory are displayed in three columns. The first column shows the address or label of the memory work. The second shows the value of the memory word using hexadecimal notation. The third shows the value of the memory word in ASCII. Breakpoints For short programs, say 20-30 instructions, single stepping through the instructions in the program is a good way to see how the program is working and to uncover errors in the logic. However, when your programs become a bit larger, say 100 instructions, this process becomes tedious and error prone -- especially when you know the first 50 instructions are correct. While you are debugging a larger program, you may find it useful to set breakpoints in the code. When tkisem is not in single stepping mode (see Processor state), it executes instructions until the program halts (using ta 0) or it is about to execute an instruction that has been identified as a breakpoint. You can set, clear, or examine breakpoints using the Breakpoint window or the Text display window. As a general rule, the breakpoint window provides a useful summary of the breakpoints you have set, but the text display window presents a much better interface for setting and clearing breakpoints and watching as instructions are executed. Note: Pressing the Run button will always execute at least one instruction. You don't have to clear the breakpoint to execute an instruction that has been identified as a breakpoint. If you are at the breakpoint instruction, pressing the Run button will execute the breakpoint instruction. The devices Currently, tkisem supports four devices: The console, The interval timer, The UART, and The halt device. Tkisem was designed to make it relatively easy to new devices. If you are interested in adding a new device, drop us a note, we'll be happy to offer any help we can. Device Addresses In many cases, the only piece of information you need is a table of the addresses used by the devices. Here is the table. Device Addresses Console 0x110000--0x11ffff Halt 0x120000--0x12ffff Timer 0x130000--0x13ffff UART 0x140000--0x14ffff The console The console provides a single basic, character I/O capabilities. Writing a character to the console data register causes the character to be appended to the [Console output]. Reading a character from the console data register gets the next character from the console. If there are no characters available, reading the console data register returns the value 0xffffffff. The console data register is mapped into location 0x110000 in both the user and supervisor address spaces. The halt device For the most part, tkisem tries to present a full emulation of a SPARC processor and hardware devices. To this end, all traps, exceptions, faults, and interrupts are handled by SPARC code. The halt device is one of the few concessions tkisem makes to the fact that it is really a program and not a processor. When a program reads from or writes to the halt device, tkisem stops executing instructions. In effect, this halts the execution of the program. The halt device is mapped into location 0x120000 in both the user and supervisor address spaces. The interval timer The interval timer provides a single register in the user and supervisor address spaces. This register is called the timer period register. The timer period register establishes the period, measured in instructions executed, between interrupts. In addition to the timer period register, the interval timer maintains an internal count register. When you write a value to the timer period register, the count register is initialized to zero. If the period is nonzero, the count register is incremented after each instruction execution. When the count value is the same as the period, the count is reset to zero and the timer generates a level 1 interrupt. The interrupt can be cleared by reading or writing the timer period register. The Timer window displays the timer period register, the internal count register used by the interval timer, and the interrupt status for the interval timer (0 means no interrupt pending). In addition to the displayed values, the Set period button can be used to set the timer period register. The timer period register is mapped into location 0x130000 in both the user and supervisor address spaces. The UART The UART is not documented yet (sorry). The UART window, like the UART itself, is not documented yet. The rom code The rom code provides basic system support for user level programs. This includes support for traps that support program termination and console I/O, fault handling, exception handling, and interrupt handling for the devices. Traps The following table summarizes the traps supported by the default rom code Trap # Name Operation 0 exit terminate program 1 putc print the character in %r8 on the console 2 getc get a character from the console, return the character in %r8 -- wait until a character is available 3 getc_nb get a character from the console, return the character in %r8 -- return -1 if no character is available 4 putx print the value in %r8 using hexadecimal notation 5 getx read a hexadecimal number from the console and return the value in %r8 6 puts print the NULL terminated string, whose address is in %r8, on the console Faults The tkisem rom code provides fault handlers for the register window overflow and underflow faults that may occur when a program issues ~eg[save] and ~eg[restore] instructions. Because these faults are handled by the rom code, tkisem should be able to run just about any SPARC executable. Because the rom code is written in SPARC assembly language, you can see an example of how these faults might be handled. Exceptions The tkisem rom code also provides basic support for the exceptions that may occur during the execution of a program, e.g., memory addressing exceptions. This code prints a message and terminates the program. The message includes an indication of the exception along with the values for the PC and nPC. Interrupts The tkisem rom code provides default interrupt handlers for the devices. These handlers simply discard the interrupt and, when possible, disable further interrupts. These handlers can be used as starting points for writing more sophisticated interrupt handlers. Extending and modifying the rom code If you want to experiment with the supervisor program (to modify or extend the existing handlers), you can copy the file tkisem_rom.s from the directory /home/maccabe/lib. This code can be assembled using the isem-as assembler and isem-ld linker used to assemble and link user programs. (See the comments in the tkisem_rom.s file for more information.)