CSE 378 Homework #4: Tool Setup and Use

Getting/Updating the Tools

You'll want the latest version of SMOK and Cebollita. The versions on lab machines will be out of date until the next cycle of reimaging, which could take a while (days to a week or so).

You want to have Version 7.2.2 or later of SMOK, and Version 2.5 (Build 48) or later of Cebollita. To check the version in SMOK, launch it, then Help / About. To see the Cebollita version, issue a command like cebsim --version.

Overview of Using the Tools

SMOK is the essential tool you need. It can execute your datapath and control. Cebollita is useful as a debugging aid. One way to determine if your processor is executing correctly is to compare the state of your SMOK machine to that of a Cebollita simulation executing the same code.

That said, there are four approaches to using these two tools to help debug your processor:

  1. SMOK Alone
    SMOK has a full interface allowing you to control execution (e.g., single step, run, stop, reinitialize) and to examine the states of the data path components. One way to debug is to load applications into the SMOK memory and to single step, checking at each step that the values in all registers (for instance) are correct. (To view register contents, right-click on the register file and select Display Contents. The same can be done to view memory contents.)

    This is a perfectly plausible approach, but will probably get tedious once you start to run bigger programs and find them not working after, say, 867 cycles.

  2. Side-by-Side SMOK and Cebollita
    Rather than having to work out yourself what 0xfc2acb0 + 0x2c193f4 is, so that you can check if you got the right answer after single stepping past an add, you can run an instance of Cebollita while you are running SMOK. Single step each one, and then check whatever register or memory location was written on each to make sure they agree. (If they disagree, Cebollita is right.) Check the PC value as well.

    This requires less concentration than method 1, but you have to hit the single-step button on two tools for each step.

    Note:For the methods described next, you must have the directory containing the file SMOKJava.dll in your PATH environment variable. That file is located with the SMOK executable, SMOK.exe, wherever you installed it (often C:\Program Files\University of Washington CSE\SMOK). Note that the lab version of SMOKJava.dll at that location will be out of date for a while. Some information about setting environment variables can be found at the bottom of this page. It talks about CLASSPATH, but the techniques for PATH are identical.

  3. Cebollita Interface to SMOK
    SMOK is a general machine organization simulator. It knows basically nothing about the Cebollita architecture. That means that it cannot disassemble 32-bit quantities in memory into readable assembler instructions, for instance.

    For that reason, you might find it useful to attach the Cebollita GUI to your SMOK machine. You do that like this: 

    cebsim --smok ceb-initial.smok myTestProgram.exe
    That will bring up SMOK and the Cebollita GUI. The Cebollita display knows about the Cebollita architecture, and will disassemble for you. The Cebollita step, run, etc. buttons will control your SMOK machine.

    Remember that all that is happening is that the GUI is examining the state of your SMOK machine. If you set a breakpoint in the Cebollita GUI, the machine will actually halt at the breakpoint only if you have implemented the break instruction in your SMOK machine -- Cebollita is not executing any of the instructions (in fact, the Cebollita simulator isn't even running - all that's running is the GUI front end).

    You can interact with your machine through both the Cebollita and SMOK interfaces (e.g., to single-step it). Getting Java (Cebollita) to talk with C++ (SMOK) through a DLL (Windows) is a bit precarious, though, so if I were you I wouldn't go too wild using the SMOK interface to change the model in drastic ways while running in this mode.

    This facility has been operational for a year, but has had light use. I'd appreciate hearing any bug reports.

  4. Lockstep Execution of Cebollita and SMOK Simulators
    The final way to debug is to bring up both the Cebollita simulator and your SMOK machine, and to have them execute instructions in lockstep and to do a heuristic check that they have arrived at the same result after each instruction. (The PCs are compared, as well as any register or memory location written by the last instruction.) Doing this has two effects, one expected and one miraculous:

    1. You can just load your test program and hit run. The machine will automatically halt if it detects the SMOK machine has made a mistake, relieving you of the tedium of checking the results for the 8,000th time. (Some hand checking is instructional, I think. Doing it 8,000 times is not, however.)

      Note that this test can be in error. SMOK and Cebollita do not agree completely on things like the values in uninitialized memory locations when your program starts. (The same could be true of register values.) Working programs don't use uninitialized values, though, so for reasonable test programs this shouldn't cause a problem.

    2. You can run programs that make system calls, like doing IO, and actually see the results, without having to build any syscall support into your SMOK machine. This means you can run applications that call printString for instance. You can also set breakpoints through the Cebollita interface (right-click on an instruction), and they work, again without implementing any SMOK support for this.

      How does this work? Your SMOK machine executes the SYSCALL as a no-op. The Cebollita machine, however, executes the SYSCALL, but only in Java code: it doesn't affect the state of the machine being simulated (the register contents, for instance). This means that the Cebollita side prints the string for a printString syscall, so you see it, and that the two machines stay synchronized (because their PCs both advance to the next instruction, and no registers or memory have been affected). A similar chain of events occurs for breakpoints.

    You invoke this style of execution like this: 

    cebsim --sync ceb-initial.smok myTestProgram.exe
    This functionality is approximately 12 hours old (built especially for your use this quarter). I used it extensively while building a solution for this assignment, though, without problem. (The caveat about not making major changes to your SMOK model, like deleting all but one component, applies in this mode as well.)

    If you encounter bugs, I'd appreciate hearing about them. (Direct email is good, because I can ask questions to get more information if necessary, but the anonymous feedback form on the course home page would be fine as well -- much better than hearing nothing, for instance.)

SMOK Tips

  • SMOK is a Windows-only appplication.

  • You can add Halt components to your SMOK model to act as something like breakpoints -- add a Halt that stops when the PC has a particular value to get the garden variety breakpoint, for instance, or add one to stop whenever whatever condition you're worried about occurs.

  • The operations of PLA's are controlled by .smokpla files, which must be edited externally to SMOK. You can cause a PLA component in a running instance of SMOK to re-read its PLA file by reinitializing the SMOK model. (The memory component will re-read whatever file you loaded into it as well.)

  • Hovering the mouse over a SMOK component will cause a popup to appear with some information about its state. More information is usually available by right-clicking on it and selecting Properties. (Nearly all operations on components happen through the right-click menu.)