btl is the raw cycle-accurate simulator.
It matches the hardware behaviour exactly (although
the sizes of rams and number of tiles can be
configured), but has added debugging functionality.
The original goal of btl was to develop the
architecture. Then, btl's purpose was to aid
in the verification of the Raw processor.
Now, btl's purpose is to:
1) assist people in debugging and performance tuning
their applications,
2) permit simulation of Raw processors at future technology points
and
3) simulate Raw with different I/O devices than the existing Raw motherboard provides.
btl features a interpretive pipeline simulation
engine, around which is wrapped the
bC extension language
interpreter. bC is a
reflective, cooperatively-multithreaded, interpreted
dialect of C. The interpreter automatically translates bC code into x86 assembly on the fly.
The bug user interface, motherboard hardware devices, and
machine-level
debugging support layer of the
simulator are all written in bC. It is very easy to
add your own commands and devices by writing your
own .bc code. In fact,
I recommend that you do so.
btl replaces rawsim, which
was much less accurate. if you should see references
to rawsim in a
document, it is likely that you are reading an outdated version..
For more information about the Raw architecture, please refer to the
Raw specification, on the Raw
website.
Creating an executable
The process of building a btl executable is exciting
enough that one should not attempt it by hand.
Fortunately, the makefiles
provided in the starsearch/starbuild directory Note that there are two types of executable:
Firing it Up
We recommend that you make use of the starsearch/starbuild infrastructure for
gmake debug
In general, btl allows you to configure the number of X and Y tiles, What you see
btl checks to see if the input tty is interactive. If it is not, then
it will not bother setting up
If you do run btl interactively, two windows will appear:
The Code Window
TILE 0_ <Bypass> ciesrwB
The "E" indicates the instruction that is in the execute unit at that
moment. The "S" points
The characters after "TILE 0" indicate the
status of the tile. The "_" means that the switch is stalled. At
any The follow commands apply in the code window:
Note however, that the output of these commands may not be reflected
in the shunt
When you start up the program, you will see something like:
No /u/mtaylor/.shuntc: using default colorization
Configuration:
[NUMBER DEVICE NAME RESET ROUTINE
CALC ROUTINE
PARAM ]
[00468f50 Serial Rom dev_serial_rom_reset
dev_serial_rom_calc 004634b0]
/*[0] 0*/
The first line is informing you that you don't have a color configuration
file. This feature
/*[0] 0*/ help(); help("help");
name
help root
[-------------------- ---<Links>---------------------------------------------
api
<more> Programmatic functions for user extension.
[-------------------- ---<Fields>--------------------------------------------
name
help
[-------------------- ---<Links>---------------------------------------------
You just called the two versions of btl's help() function. The first
lists all of the functions
Let's look at the help. Let's find out how to step.
/*[4047] 2*/ help("step");
name
step
From this we can tell step takes one parameter. Let's use it.
/*[4236] 4*/ step(1);
If you look at the code window, you will have noticed that the state
of the raw tiles
There is also a go() command, which runs the tiles indefinitely
until the tiles are halted.
You can interrupt the go command by moving the mouse to the codewindow
and hitting Ctrl-C.
You can look for other commands by using the help function (shown above)
or by using the
The regs(tileNum) command shows the contents of the registers as well as
the instructions
/*[0] 1*/ regs(0); You can look for other commands by using the help function (shown above) or
by using the /*[1853170] 6*/ <tab> <tab>
Ctrl-D closes the shunt window.
The Vis Window
The vis window (toggled by hitting the
"v" key in the code window) shows the contents of the
the general
network.
appear in the
tile icon when elements are in the N, E, S, W, or P (north, east, south, west,
or processor-out) FIFO of the tile. The color is
determined by the value of the data element. The N, E, S, and W FIFOs elements
appear are on the top, left, bottom and west portion of the plus sign,
while the processor-out FIFO elements appear in
a diagonal pattern. A black box with red diagonal indicates
a value of 0xDEFACADE travelling through the network. 0xDEFACADE is the value given to
uninitialized data coming from DRAM. This is not necessarily an error condition, because
the caches are allocate-on-write, causing uninitialized data to pulled into the cache on a
store to uninitialized memory.
Note
that because static network 1 and static network 2 share the csto port, these
values will appear in both network sub-windows.
The vis window can also show the contents of the networks for multi-chip systems.
A black box is drawn around each group of tiles that comprises a Raw
chip.
The "r" command can be hit in the code window to toggle the order of the networks shown.
The "vis" command in the shunt window can be used to create a
cycle-by-cycle animation of the network. Use help("name") on these commands for description of their arguments.
step
// step N cycles
dump_mem (or dm)
// dumps DRAM memory w/ cache info / coherency checking
bp
// set watchpoints on arbitrary bool expression
pins_print(port)
// shows what's crossing the pins of each io_port
gdn_print
// "" general dynamic network
sn_print (or sp)
// show dump of static switch
sv
// show graphical execution trace (.ppm)
vis(num_cycles)
// cycle-by-cycle graphical visualization of networks
dump_sprs
// print out contents special purpose registers
regs
// print out register values
Use help() on these commands for description of their arguments. Remember,
with the exception
will do
all of the work for you.
.rbf - the raw boot format. Technically for tests
and the OS boot rom only.
However, in practice, it's the fastest way to directly to
your code, so many people use this.
This uses the snakeboot boot process.
.rexe - a standard Raw executable, loaded after the OS.
configuring your btl session. It invokes btl with all of the necessary
parameters the describe the environment around the raw chip that you
are simulating.
will do the trick if you are using starsearch/starbuild (and you should.)
the devices that sit on the outside of the tiles, the sizes of the rams,
any debugging/performance counting features that you may want to add, and much more.
the pretty interface. Thus, you can specify an input .bC file to script
btl and an output file to
capture the output.
A curses style window which displays the instruction streams of the
processors at any
The Shunt Window
point in time. You may have to resize the window in order to see all
of the processors.
A portion of each tile's instruction stream is displayed. You will
notice that some of the
instructions are tagged with letters like "E" and a "S".
function
label
FFFF4 <invalid>
FFFF8 <invalid>
FFFFC <invalid>
E 00000 lui $sp,0
S 00004 ori $sp,$sp,20
00008 jal 6
0000C add $0,$0,$0
00010 j 4
00014 halt
to the instruction that fetch unit thinks is the next instruction (this
instruction may never execute).
On the processor, the letters S/E/T/M/F/W correspond to the stall,
execute, tag, memory
floating point, and writeback stages. On the switch, the letters E/R
correspond to the Execute
and Recovery stages. The "R" stage is the commit point for the switch.
(In other words, instructions
in the execute stage have not actually executed yet.) The line labelled
"function"
contains the text of the most recent previous global symbol. The line
labelled "label" contains
the text of the most recent previous local symbol. Note, in order to
get this information when
debugging a .rbf file, the simulator will look for a corresponding
.rexe file to match the .rbf file. Only
.rexe have symbols. This functionality is mostly a hack, and you should
treat it with a grain of
salt. In particular, local symbols don't have much meaning in anything
except assembly code.
point an time, there may be multiple reasons for which the main processor is
stalled. The string inside the
< > symbols indicates one of the reasons that processor is
currently stalled. The pattern of letters ciesrwB gives
a more thorough representation of all of the causes for a stall. A
letter is capitalized if it is responsible for a stall. For reference,
ciesrwb => cache miss, imem access, exception
(i.e., interrupt), resource conflict, net read stall, net write
stall, bypass stall)
g
run until interruption
s
step the chip exactly one cycle
x
step the chip until some tile issues an instruction
v
turn on/off network visualization
r
rotate network visualization order
t
toggle window to show switch code instead
q
quit
0 .. 9
go to the next instruction on tile N
Ctrl-C
interrupt simulation
Arrow Keys
Change Tiles Visible in Code Window
`
go(); go_to(0,"begin");
window until you hit "enter" in the shunt window. In fact, if you have
enough output,
the simulator may block because it has filled up the output pipe to
the shunt window.
You can hit enter to clear things up.
A readline-style text input window. This is the window you use to control
btl. You can
hit tab to auto-complete commands, similar to emacs. You can also use the arrows
keys to cycle through previous commands. It runs as a separate process,
and communicates
through named pipes with the codewindow.
// try:
help(); help("help");
[004896d8 Print Service dev_print_service_rese dev_print_service_calc
00463500]
[004aa068 DRAM
dev_dram_reset dev_dram_calc
00463550]
[004ca9f8 DRAM
dev_dram_reset dev_dram_calc
004635c8]
[004eb388 DRAM
dev_dram_reset dev_dram_calc
00463640]
[0050bd18 DRAM
dev_dram_reset dev_dram_calc
004636b8]
[0052f838 PCI Bus dev_pci_bus_reset
dev_pci_bus_calc 004637a8]
[001405f0 PCI Bridge - P dev_pci_bridge_reset dev_pci_bridge_pci_sid
00463780]
[00140958 PCI Bridge - R dev_pci_bridge_reset dev_pci_bridge_raw_sid
00463780]
[005a2b40 Filesys dev_filesys_reset
dev_filesys_calc 00595290]
was added by Walter Lee. It allows you to colorized any string in the
shunt window.
The third line is a suggested command that new users can try to get
on their feet. The next
section is a list of all of the devices that are installed on this
simulation machine.
The last line is the prompt. It is in the form of a comment so
that it will be ignored when you
cut and paste. It contains the command number, and the number of microseconds
it took to
execute the last command. So, to get started, highlight the third and
fourth line with your mouse and
paste it in to the shunt window.
[-------------------- ---<Fields>--------------------------------------------
lines0
lines1
'help("functionname");' if you know the name of the fn
lines2
'help(<path>);'
lines3
if you are trying to look up a fn, to follow links
lines4
e.g. help(help);
lines5
help(help.user);
lines6
help(help.user.static);
lines7
help(help.user.static.network);
user
<more> Functions intended purely for user interface
all
<more> All of the functions, jumbled in a soup
lines0
lines1
Usage: help();
lines2
help(char *functionname);
lines3
help(help.link.link);
lines4
brief
Prints out functions registered by new_help_descr()
that help is available. The second lists help on the "help" command.
As you can see,
bug commands look very much like C commands. In fact, bug runs a C-like
interpreter
as its interface. The syntax is exactly the same as C, except for a
few minor differences
having to do with types.
lines0
lines1
Usage: int step(int numSteps);
lines2
brief
Causes the simulator to execute numSteps steps
has been updated to one cycle later. There is an abbreviation function
you can use
instead of step(1). It is s(); It has the same purpose.
/*[5951] 5*/ go();
running...
1105 cycles executed
stopped.
command completion feature of the shunt window. In fact, if you hit
tab twice, you will get
a listing of all of the variables and functions that exist with in
the bC/bug environment.
and operand values traveling down the pipeline. A question mark indicates
that the simulator does not yet know what the result will be. If the question mark
precedes a value, it indicates the simulator's best guess. This command can be used
to examine the instructions that were executed immediately preceding the current instruction.
This is useful, for instance, if the processor jumps to an invalid address, and the user wants
to find the offending instruction.
p0 PC = 646c72
p0 00000000 0000cafe 00000000 07ffffe2 00000002 07ffffd0 07ffffc0 00000002
p0 00000000 42000000 07ffffe0 00000000 00003076 0000cafe 0000cafe 0000cafe
p0 0000000c 07ffffc0 6f77006f 0000cafe 0000cafe 0000cafe 0000cafe 0000cafe
p0 00000000 00000000 00000000 00000000 00000000 07ffffb8 0000cafe 00646c72
E: PC = 00646c72 nop
T: PC = 0000068c jr $31,
RS=0x00646c72
M: PC = 00000688 addiu $sp,$sp,30
regs[29] <= 0x07ffffe8 RS=0x07ffffb8 SIMM=0x00000030
F: PC = 00000684 lw $16,20($sp)
regs[16] <= 0x00000000 RS=0x07ffffb8 SIMM=0x00000020
W: PC = 00000680 lw $17,24($sp)
regs[17] <= 0x6c6c6568 RS=0x07ffffb8 SIMM=0x00000024
s0 PC = 58
s0 00000000 00000000 00000000 00000058
command completion feature of the shunt window. In fact, if you hit tab twice,
you will get
a listing of all of the variables and functions that exist with in the bC/bug
environment.
Display all 1245 possibilities? (y or n)
Other useful commands
the network buffers for a given cycle. The red bars separate the four
logical networks, which are,
in order, (as indicated by title bar): static network 1, static
network 2, the memory network, and
Each logical network consists of an array of tile icons (they look
like plus signs). Colored boxes will? <expression>;
// just like basic; prints out what you want. hex/dec/float
Passing GO
// also prints out hms structs.
list_sw
// shows switch instructions
list
go
// go until interrupted
go_to
// run until a reach a particular function name on a tile.
stop_at
// set a one-time break point at a particular function name
s
// step 1 cycle
dump_instr_mem
// dump processor instruction SRAM
dump_switch_mem
// dump switch proc instruction SRAM
bp_list
// list breakpoints
bp_remove
// remove breakpoint
io_mux_print(port)
// shows what's going on in the chip's io_muxes
device_io_mux_print(port)
// shows what's going on in the .bc device's io_muxes
mdn_print
// "" memory dynamic network
white
non-floating point op
magenta
floating point operation
red
net receive stall
blue
net send stall
green
resource/bypass stall
black
cache stall
yellow (yellow)
instruction memory write/read stall
? pNrM;
// print individual reg value
// where N = tile, M = [0..31, pc, sp, at, gp]
// note: these are actual contents of register file,
// does not include bypassing!
of the "?" commands, these are all function calls, and require parenthesis,
parameters, and a semicolon.This concludes our in-flight presentation. It
should be enough to get you running the simulator.
For more information on the programming environment
and how to add your own functionality,
look at the
advanced btl document
, the *.bc files in the btl installation or email
the starsearch mailing list.