Cebollita ISA Simulator/Debugger Last modified: January 13, 2006

CSE Home

About Us

Search

Contact Info

Introduction

The Cebollita toolkit provides a basic Cebollita ISA simulator. Two user interfaces are provided: graphical and text-oriented. Unlike SPIM, this simulator does not itself include an assembler -- things are done in a more realistic way, with the simulator loading and runing executables produced by other Cebollita tools.

Choosing a Simulator Target Configuration

The debugger can be configured to control a number of different Cebollita configuration and implementations:

• It can serve as the front-end for both the built-in Cebollita software simulator and to a SMOK implementation of the Cebollita architecture.
• You can choose to run with no SYSCALL support, with SYSCALL support delivered by the Cebollita software simulator itself, or with SYSCALL support delivered by the Cebollita operating system running on the simulated processor.
• You can choose an I/O and interrupt architecture. Currently there are two implementations: Classic (deprecated), which follows the description in Patterson and Hennesy, and Simple, which is much easier to implement.

Starting the Simulator

We'll assume in this document that you want to run with Cebollita support for handling SYSCALL's, and with the Simple architecture. The graphical simulator is started as follows:

java dbg.UI [exefile]

[exefile] is the filename of an executable in the Cebollita EXE format. The simulator's loader will load the text and data segments, set up the stack and global pointers appropriately, and jump to the entry point of the program.

The Simulator Window

Once the simulator starts, the user should see a window like the following:

The window is split into four panes, which show, respectively:

1. Instruction memory (based on wherever the PC is)
2. Data memory (based on where $GP points)
3. Stack memory (based on where $SP points)
4. Machine registers

Right-clicking on an instruction will set/unset a breakpoint at that location.

Breakpoints

If the user hits the "Show Breakpoints" button, a window like the following will be produced (assuming they've set two breakpoints):

Each line shows the address and instruction at which a breakpoint was set. Clicking on a breakpoint will "seek" the instruction memory window to the address of the breakpoint.

Console Based Simulator

For the console-oriented folks, there's a simple console oriented simulator as well. Start it as follows:

java dbg.Debugger [exefile]

Typing "help" will give a list of commands. Here's an overview of what's currently implemented:

Command	Meaning
help	Dump a help message.
s	Step one instruction
sn [n]	Step n instruction
r	Run the program
trace	Toggle tracing (be verbose)
show	Show the machine state
sb [addr]	Set a break at the given address
db [addr]	Delete a break at the given address
lb	List all breakpoints
rm [addr]	Read memory at [addr]
wm [addr] [value]	Write the memory at [addr] with the given [value]
lm [addr] [words]	List [words] of memory starting at [addr]
q	quit

Simulator Details

The simulator has two basic modes of execution.

System mode: In this mode, the simulator actually manages many of the system services, namely system calls. A set of system calls is provided to perform basic IO, which is all simply handled in software. These are defined below. Beginning users will probably spend most of their time running the simulator in this (default) mode. Most of the details below need not worry them in that case.

Bootable mode: In this mode, the simulator is given a "disk image" rather than an executable as an argument. Upon startup, the simulator's "BIOS" loads the OS loader (bootloader) from the given disk image. The bootloader must be able to fit in a single 512 byte block and run in a location independent manner. Its job is to load the OS into low memory. The OS is standard-looking executable and the bootloader can just slam it into memory starting at location zero. (Detail: the OS is linked as if it starts at location 20, because the top 5 words are always the executable descriptor -- the OS can reuse this space later, if it wishes.

Once the kernel is loaded, the bootloader should jump to its entry point (as specified by the executable) and it's off to the races. In this mode, memory mapped IO is used, and it's the kernel's responsibility to provide system calls to read/write from these addresses to perform IO. If the kernel wishes to load/run other processes, it must manage the base & length registers accordingly to perform address translation for that process.

A bootloader, simple OS, and simple shell are part of the standard Cebollita distribution, located in cebollita/apps/os. make image in directory cebollita/apps will produce a bootable image file, image, and a map file, image.map, giving the disk block numbers of each application on the image. (Those are the inputs to the shell, which then exec's the application at the given block.)

Memory mapped IO: By default, the machine has a single CharacterDevice, a single BlockDevice, and a single RAM. The ram is 64KB in size, by default. The Character device is connected at address 0x40000000 and the BlockDevice is connected at address 0x40000010. Details of the operation of these devices can be found elsewhere (currently in the JavaDoc). In bare mode, the user has to write code that uses these devices to do IO. In system mode, these devices are typically unused, in favor of doing IO through the system calls. However, depending on the IO interfaces provided to the user, student's can happily write their own memory mapped IO routines for system mode. (Specific documentation is available elsewhere.)

Differences from the Mips ISA:

The MULT and DIV instructions currently do not simulate the HI/LO registers as on a MIPS machine. MULT and DIV are encoded as normal R-type instructions, where the destination register takes the product (or quotient). Users wishing to implement modulus must do simulate the process in software.

MIPS Subset

The simulator only implements a subset of the MIPS ISA. See this page and this page.

System Call Simulation

The following system calls are simulated, so long as the --bootable switch isn't given:

Service	Number	Args	Result	Cebollita Simulator	Cebollita OS	Comments
print_int	1	$a0=integer		+	+	Prints in the console window
print_string	4	$a0=string		+	+	Prints in the console window. C-style (null terminated) strings.
read_int	5		integer in $v0	+	+	Reads from the console window (Can be redirected with --dataFile switch.)
read_char	7		integer in $v0	+	+	Reads from the console window. (Can be redirected with --dataFile switch.)
read_string	8	$a0=buffer $a1=length		+	+	Reads from the console window. (Can be redirected with --dataFile switch.)
exit	10			+	+	Stops the simulation
exec	11	$a0=disk block number			+	Reads the block(s) from the virtual disk and launches a new (simulated) process. Supported by the Cebollita OS only (i.e., you must be running with a bootable disk image containing that OS), not by the built-in system call handler.

By and large, these system calls behave like the ones described in Patterson & Hennesey A-49.

Input and output occur via the console window from which the simulator was launched. Input can be redirected (to come from a file) with the swtich --dataFile filename.

Department of Computer Science & Engineering University of Washington Box 352350 Seattle, WA  98195-2350 (206) 543-1695 voice, (206) 543-2969 FAX [comments to zahorjan@cs.washington.edu]