Debugging

FireSim Debugging

In addition to Verilator and VCS software simulation testing, one can use the FireSim tool to debug faster using an FPGA. This tools comes out of the UC Berkeley Architecture Research group and is still a work in progress. You can find the documentation and website at https://fires.im/.

Chicken Bits

BOOM supports a chicken-bit to delay all instructions from issue until the pipeline clears. This effectively turns BOOM into a unpipelined in-order core. The chicken bit is controlled by the third bit of the CSR at 0x7c1. Writing this CSR with csrwi 0x7c1, 0x8 will turn off all out-of-orderiness in the core. High-performance can be re-enabled with csrwi 0x7c1, 0x0.

Pipeline Visualization

“Pipeview” is a useful diagnostic and visualization tool for seeing how instructions are scheduled on an out-of-order pipeline.

Pipeview displays every fetched instruction and shows when it is fetched, decoded, renamed, dispatched, issued, completed, and committed (“retired”). It shows both committed and misspeculated instructions. It also shows when stores were successfully acknowledged by the memory system (“store-completion”). It is useful for programmers who wish to see how their code is performing and for architects to see which bottlenecks are constricting machine performance.

Listing 4 Pipeview Text Output (uncolored)
-(       33320000) 0x00000018a0.0 sw a0, 220(gp)
[......f.d...i...c.........r.............]-(       33320000) 0x00000018a4.0 blt s1, a2, pc + 52
[.......f.d..i.c............r............]-(       33320000) 0x00000018a8.0 slliw a5, a2, 2
[.......f.d...i...c.........r............]-(       33320000) 0x00000018ac.0 addw a5, a5, a2
[........f.d...i...c.........r...........]-(       33320000) 0x00000018b0.0 addiw a5, a5, -3
[........f.d..i.c............r...........]-(       33320000) 0x00000018b4.0 mv a0, a2
[.........f.d..i.c............r..........]-(       33320000) 0x00000018b8.0 li a1, 3
[.........f.d...i...c.........r..........]-(       33320000) 0x00000018bc.0 addi a2, s0, -184
[..........f.di...c............r..s......]-(       33320000) 0x00000018c0.0 sw a5, -184(s0)
[..........f.d...i...c.........r.........]-(       33320000) 0x00000018c4.0 jal pc - 0x1284
[...........f.d.i.c.............r........]-(       33320000) 0x0000000640.0 addiw a0, a0, 2
[...........f.d..i.c............r........]-(       33320000) 0x0000000644.0 addw a1, a0, a1
[............f.d.i..c............r...s...]-(       33320000) 0x0000000648.0 sw a1, 0(a2)
[............f.d......i...c......r.......]-(       33320000) 0x000000064c.0 ret
[.............f.d..i..c...........r......]-(       33320000) 0x00000018c8.0 lw a2, -188(s0)
[.............f.d......i...c......r......]-(       33320000) 0x00000018cc.0 addiw a2, a2, 1
[..............f.d..i.....c........r..s..]-(       33320000) 0x00000018d0.0 sw a2, -188(s0)
[..............f.d......i...c......r.....]-(       33320000) 0x00000018d4.0 bge s1, a2, pc - 44
[...............f.d..i..c...........r....]-(       33320000) 0x00000018d8.0 lw a3, -184(s0)
[...............f.d...i..c..........r....]-(       33320000) 0x00000018dc.0 ld a0, -200(s0)
[................f.di...c............r...]-(       33320000) 0x00000018e0.0 addi a1, gp, 256
[................f.d.i...c...........r...]-(       33320000) 0x00000018e4.0 jal pc - 0x1294
[.................f.d...i.c...........r..]-(       33320000) 0x0000000650.0 addiw a6, a2, 5
[.................f.d....i...c........r..]-(       33320000) 0x0000000654.0 mv a5, a6

To display the text-based pipeline visualizations, BOOM generates traces compatible with the O3 Pipeline Viewer included in the gem5 simulator suite.

To enable pipeline visualization, first set O3PIPEVIEW_PRINTF in src/main/scala/common/consts.scala to true:

val O3PIPEVIEW_PRINTF = true // dump trace for O3PipeView from gem5

Rebuild and rerun BOOM. You should find the traces (*.out) in the verilator/output/ or vcs/output/ directories if you are using chipyard to run the core. To generate the visualization, first download and install gem5, and then run:

boom/util/pipeview-helper.py -f <TRACE_FILE> > clean_trace.out
gem5/util/o3-pipeview.py --color --store_completions -o pipeview.out clean_trace.out

You can view the visualization by running:

less -r pipeview.out

To learn more about o3-pipeview.py and to download gem5 visit http://www.m5sim.org/Visualization.