cpu-lang/rvddt

RISC-V Dynamic Debugging Tool

rvddt

RISC-V Dynamic Debugging Tool

This is an RV32I simulator that was written to gernerate the figures for a book in progress here: https://github.com/johnwinans/rvalp that will (eventually) include several examples on how to use rvddt and other tools mentioned below.

To build everything:

mkdir -p ~/projects/riscv
cd ~/projects/riscv
git clone https://github.com/johnwinans/rvddt.git
cd rvddt/src
make world
cd ../examples
make world
echo "export PATH=$PATH:~/projects/riscv/rvddt/src" >> ~/.bashrc

Note that you will need a suitable compiler to build the examples.
On Ubuntu, I installed mine like this:

sudo apt-get install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev \
	libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils \
	bc zlib1g-dev libexpat-dev
mkdir -p ~/projects/riscv
cd ~/projects/riscv
git clone https://github.com/riscv/riscv-gnu-toolchain
cd riscv-gnu-toolchain
INS_DIR=~/projects/riscv/install/rv32i
./configure --prefix=$INS_DIR --with-arch=rv32i --with-abi=ilp32
make
echo "export PATH=$PATH:~/projects/riscv/install/rv32i/bin" >> ~/.bashrc

If you are new to building the GNU tools be careful about following the numerous opinions on how to configure them. rvddt will ONLY execute instructions in the rv32i base ISA. Configure and/or use the tools appropriately!

See the rvddt examples and their makefiles for help figuring out how to run the compiler.

After building, the rvddt executable will be left sitting in the src directory.
Put it wherever you want to install it. I just run it from the src directory like this:

rvddt -f proggie.bin

To ask for command-line help, run it like this:

rvddt -h

All the regs ('cept x0) are set to 0xf0f0f0f0 and the memory is filled with 0xa5 prior to reading the binary memory image into memory starting at address zero and initializing the sp register and priming the stack top as discussed below.

By default rvddt will create a memory space starting at 0 with a size of 0x10000, set the pc register to zero, the sp register to the last memory address +1. You can see this initialization in the pre-trace register dump in the same output below. (Note that you can change the memory size with the-l <memlen> arg and the stack initialization will follow it.)

If your program reads or writes outside of the simulated memory region a warning will be printed to help you track down the instruction that did it. In dumps, such 'unimplemented' memory bytes are all 0xff.

The simulator will stop on an illegal instruction or an ebreak.

To see a list of commands type ? at the prompt:

ddt> ?
commands:
   a                 toggle the display of register ABI and x-names
   d [addr [len]]    dump memory starting at addr for len bytes
   g [addr]          set pc=addr and silently execute qty instructions
   r                 dump the contents of the CPU regs
   t [[addr] qty]    set pc=addr and trace qty instructions
   ti [[addr] qty]   set pc=addr and trace qty instructions w/o reg dumps
   x                 exit
   > filename        redirect output to 'filename' (use - for stdout)
ddt> 

The way you use rvddt is to create an executable binary memory image with its entry point (the first instruction to execute) located at address 0 and then run it like this:

$ rvddt -f examples/load4regs/load4regs.bin
sp initialized to top of memory: 0x00010000
Loading 'examples/load4regs/load4regs.bin' to 0x0
This is rvddt.  Enter ? for help.
ddt> t1000
   x0 00000000 f0f0f0f0 00010000 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   x8 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x16 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x24 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   pc 00000000
00000000: 00000e13  addi    x28, x0, 0    # x28 = 0x00000000 = 0x00000000 + 0x00000000
   x0 00000000 f0f0f0f0 00010000 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   x8 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x16 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x24 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  00000000 f0f0f0f0 f0f0f0f0 f0f0f0f0
   pc 00000004
00000004: 00000e93  addi    x29, x0, 0    # x29 = 0x00000000 = 0x00000000 + 0x00000000
   x0 00000000 f0f0f0f0 00010000 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   x8 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x16 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x24 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  00000000 00000000 f0f0f0f0 f0f0f0f0
   pc 00000008
00000008: 00000f13  addi    x30, x0, 0    # x30 = 0x00000000 = 0x00000000 + 0x00000000
   x0 00000000 f0f0f0f0 00010000 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   x8 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x16 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x24 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  00000000 00000000 00000000 f0f0f0f0
   pc 0000000c
0000000c: 00000f93  addi    x31, x0, 0    # x31 = 0x00000000 = 0x00000000 + 0x00000000
   x0 00000000 f0f0f0f0 00010000 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
   x8 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x16 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0
  x24 f0f0f0f0 f0f0f0f0 f0f0f0f0 f0f0f0f0  00000000 00000000 00000000 00000000
   pc 00000010
00000010: ebreak
ddt>

If you prefer the ABI register names, then use the a command and run it like this:

$ ./src/rvddt -f examples/counter/counter.bin
sp initialized to top of memory: 0x00010000
Loading 'examples/counter/counter.bin' to 0x0
This is rvddt.  Enter ? for help.
ddt> a
ddt> t
  zero 00000000  ra f0f0f0f0  sp 00010000  gp f0f0f0f0
    tp f0f0f0f0  t0 f0f0f0f0  t1 f0f0f0f0  t2 f0f0f0f0
    s0 f0f0f0f0  s1 f0f0f0f0  a0 f0f0f0f0  a1 f0f0f0f0
    a2 f0f0f0f0  a3 f0f0f0f0  a4 f0f0f0f0  a5 f0f0f0f0
    a6 f0f0f0f0  a7 f0f0f0f0  s2 f0f0f0f0  s3 f0f0f0f0
    s4 f0f0f0f0  s5 f0f0f0f0  s6 f0f0f0f0  s7 f0f0f0f0
    s8 f0f0f0f0  s9 f0f0f0f0 s10 f0f0f0f0 S11 f0f0f0f0
    t3 f0f0f0f0  t4 f0f0f0f0  t5 f0f0f0f0  t6 f0f0f0f0
   pc 00000000
00000000: 00300293  addi    t0, zero, 3   # t0 = 0x00000003 = 0x00000000 + 0x00000003
ddt>

Note that when an instruction is traced a comment is displayed explaining what the instruction did and what values it used. I originally added this feature to debug rvddt. But I think it is very useful instructional tool... so I kept it in.

rvddt is more of a STATIC debugging tool at the moment. 😄 It has no commands for the editing of registers or memory.