qtrvsim_cli.md · KevinMX/qtrvsim test

# qtrvsim 命令行工具使用手册

## qtrvsim_cli 命令行工具

命令行工具的帮助如下

```bash
$ qtrvsim_cli --help
Usage: qtrvsim_cli [options] FILE
QtMips CLI machine simulator

Options:
  -h, --help                         Displays help on commandline options.
  --help-all                         Displays help including Qt specific
                                     options.
  -v, --version                      Displays version information.
  --asm                              Treat provided file argument as assembler
                                     source.
  --pipelined                        Configure CPU to use five stage pipeline.
  --no-delay-slot                    Disable jump delay slot.
  --hazard-unit <HUKIND>             Specify hazard unit implementation
                                     [none|stall|forward].
  --trace-fetch, --tr-fetch          Trace fetched instruction (for both
                                     pipelined and not core).
  --trace-decode, --tr-decode        Trace instruction in decode stage. (only
                                     for pipelined core)
  --trace-execute, --tr-execute      Trace instruction in execute stage. (only
                                     for pipelined core)
  --trace-memory, --tr-memory        Trace instruction in memory stage. (only
                                     for pipelined core)
  --trace-writeback, --tr-writeback  Trace instruction in write back stage.
                                     (only for pipelined core)
  --trace-pc, --tr-pc                Print program counter register changes.
  --trace-wrmem, --tr-wr             Trace writes into memory.
  --trace-rdmem, --tr-rd             Trace reads from memory.
  --trace-gp, --tr-gp <REG>          Print general purpose register changes.
                                     You can use * for all registers.
  --dump-registers, --d-regs         Dump registers state at program exit.
  --dump-cache-stats                 Dump cache statistics at program exit.
  --dump-cycles                      Dump number of CPU cycles till program
                                     end.
  --dump-range <START,LENGTH,FNAME>  Dump memory range.
  --load-range <START,FNAME>         Load memory range.
  --expect-fail                      Expect that program causes CPU trap and
                                     fail if it doesn't.
  --fail-match <TRAP>                Program should exit with exactly this CPU
                                     TRAP. Possible values are I(unsupported
                                     Instruction), A(Unsupported ALU operation),
                                     O(Overflow/underflow) and J(Unaligned
                                     Jump). You can freely combine them. Using
                                     this implies expect-fail option.
  --d-cache <DCACHE>                 Data cache. Format
                                     policy,sets,words_in_blocks,associativity
                                     where policy is random/lru/lfu
  --i-cache <ICACHE>                 Instruction cache. Format
                                     policy,sets,words_in_blocks,associativity
                                     where policy is random/lru/lfu
  --read-time <RTIME>                Memory read access time (cycles).
  --write-time <WTIME>               Memory read access time (cycles).
  --burst-time <BTIME>               Memory read access time (cycles).
  --serial-in, --serin <FNAME>       File connected to the serial port input.
  --serial-out, --serout <FNAME>     File connected to the serial port output.
  --os-emulation, --osemu            Operating system emulation.
  --std-out, --stdout <FNAME>        File connected to the syscall standard
                                     output.
  --os-fs-root, --osfsroot <DIR>     Emulated system root/prefix for opened
                                     files

Arguments:
  FILE                               Input ELF executable file or assembler
                                     source
```

### 模拟器功能验证

以一个简单的加法程序为例

```c
// sum2vars.c

int var_a = 0x1234;
int var_b = 0x5678;

int var_c = 0x0000;
 
int main()
{
  var_c = var_a + var_b;
  var_a = var_c + var_b;
 
  return 0;
}
```

由于该程序只有一个 ``main()`` ，我们需要首先初始化 CPU 的状态，再跳转到 main() 函数入口

```c
// start.S

.globl   _start
.text
.option norelax
 
_start:
     la x2, _end+0x4000
     la x3, __global_pointer$
     jal  main
     ebreak
```

构建所需的 ELF 裸机二进制

```bash
$ riscv64-elf-gcc -march=rv32i -mabi=ilp32 -nostdlib -c sum2vars.c -o sum2vars.o
$ riscv64-elf-gcc -march=rv32i -mabi=ilp32 -nostdlib -c start.S -o start.o
$ riscv64-elf-gcc -march=rv32i -mabi=ilp32 -nostdlib sum2vars.o start.o -o sum2vars-riscv -lgcc
```

验证一下确实可以能跑

```bash
$ qtrvsim_cli sum2vars-riscv
[INFO]  machine.ProgramLoader:  Loaded executable: 32bit
Machine stopped on BREAK exception.
```

可以看到模拟器载入二进制并运行完毕，且没有报错

### 追踪运行过程

为了方便功能演示，这里用汇编重写上面的加法程序

```c
// sum2vars.S
.globl _start
 
.text
_start:
        lw   x4, var_a(x0)
        lw   x5, var_b(x0)

add  x6, x4, x5
        sw   x6, var_c(x0)

add  x4, x6, x5
        sw   x4, var_a(x0)
 
        addi x2, x0, 0
        jr   ra

.data
.org 0x400
var_a:  .word 0x1234
var_b:  .word 0x5678
var_c:  .word 0x0000
```

可以使用 ``--asm`` 参数指定直接运行汇编文件而不是二进制

```bash
$ qtrvsim_cli --asm sum2vars.S
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
$ echo $?
1
```

出现了报错，使用 ``--trace-pc`` 查看程序寄存器的变化

```bash
$ qtrvsim_cli --asm --trace-pc sum2vars.S
PC: 200
PC: 204
PC: 208
PC: 20c
PC: 210
PC: 214
PC: 218
PC: 21c
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

同时使用 ``--trace-fetch`` 查看取指

```bash
qtrvsim_cli --asm --trace-pc --trace-fetch sum2vars.S
Fetch: lw x4, 1024(x0)
PC: 200
Fetch: lw x5, 1028(x0)
PC: 204
Fetch: add x6, x4, x5
PC: 208
Fetch: sw x6, 1032(x0)
PC: 20c
Fetch: add x4, x6, x5
PC: 210
Fetch: sw x4, 1024(x0)
PC: 214
Fetch: addi x2, x0, 0
PC: 218
Fetch: jalr x0, 0(x1)
PC: 21c
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到我们关心的指令都有被正常运行。

下面使用 ``--trace-gp '*'`` 查看所有寄存器的变化

```bash
$ qtrvsim_cli --asm --trace-pc --trace-gp '*' sum2vars.S
PC: 200
GP 4: 1234
PC: 204
GP 5: 5678
PC: 208
GP 6: 68ac
PC: 20c
PC: 210
GP 4: bf24
PC: 214
PC: 218
GP 2: 0
PC: 21c
GP 0: 220
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到两次加法过后 6 号寄存器和 4 号寄存器分别发生的变化

最后使用 ``--trace-wrmem`` 和 ``--trace-rdmem`` 追踪数据与存储器的交互情况

```bash
$ qtrvsim_cli --asm --trace-pc --trace-wrmem --trace-rdmem sum2vars.S
PC: 200
MEM[400]:  RD 1234
PC: 204
MEM[404]:  RD 5678
PC: 208
PC: 20c
MEM[408]:  WR 68ac
PC: 210
PC: 214
MEM[400]:  WR bf24
PC: 218
PC: 21c
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到 ``lw`` 指令和 ``sw`` 指令从/向内存特定的位置读取/写入了数据

### 五级流水线模式

使用 ``--pipelined`` 参数切换到五级流水线模式，有四个选项 ``--trace-decode`` 、 ``--trace-execute`` 、 ``--trace-memory`` 和 ``--trace-writeback`` 仅用于该模式

```bash
qtrvsim_cli --asm --pipelined --trace-fetch --trace-decode --trace-execute --trace-memory --trace-writeback sum2vars.S
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Fetch: lw x4, 1024(x0)
Decode: lw x4, 1024(x0)
Memory: lw x4, 1024(x0)
Writeback: lw x4, 1024(x0)
Fetch: lw x5, 1028(x0)
Decode: lw x5, 1028(x0)
Memory: lw x5, 1028(x0)
Writeback: lw x5, 1028(x0)
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Fetch: add x6, x4, x5
Decode: add x6, x4, x5
Memory: add x6, x4, x5
Writeback: add x6, x4, x5
Fetch: sw x6, 1032(x0)
Decode: sw x6, 1032(x0)
Memory: sw x6, 1032(x0)
Writeback: sw x6, 1032(x0)
Fetch: add x4, x6, x5
Decode: add x4, x6, x5
Memory: add x4, x6, x5
Writeback: add x4, x6, x5
Fetch: sw x4, 1024(x0)
Decode: !sw x4, 1024(x0)
Memory: sw x4, 1024(x0)
Writeback: sw x4, 1024(x0)
Fetch: addi x2, x0, 0
Decode: addi x2, x0, 0
Memory: addi x2, x0, 0
Writeback: addi x2, x0, 0
Fetch: jalr x0, 0(x1)
Decode: jalr x0, 0(x1)
Memory: jalr x0, 0(x1)
Writeback: jalr x0, 0(x1)
Fetch: nop
Decode: !nop
Memory: nop
Writeback: nop
Fetch: nop
Decode: nop
Memory: nop
Writeback: nop
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到指令流入过程

### 处理器状态

使用 ``--dump-registers`` 查看程序结束后的寄存器情况

```bash
$ qtrvsim_cli --asm --dump-registers sum2vars.S
Machine state report:
PC:0x00000004
R0:0x00000000 R1:0x00000000 R2:0x00000000 R3:0x00000000 R4:0x0000bf24 R5:0x00005678 R6:0x000068ac R7:0x00000000 R8:0x00000000 R9:0x00000000 R10:0x00000000 R11:0x00000000 R12:0x00000000 R13:0x00000000 R14:0x00000000 R15:0x00000000 R16:0x00000000 R17:0x00000000 R18:0x00000000 R19:0x00000000 R20:0x00000000 R21:0x00000000 R22:0x00000000 R23:0x00000000 R24:0x00000000 R25:0x00000000 R26:0x00000000 R27:0x00000000 R28:0x00000000 R29:0x00000000 R30:0x00000000 R31:0x00000000
mvendorid: 0x00000000 marchid: 0x00000000 mimpid: 0x00000000 mhardid: 0x00000000 mstatus: 0x00000000 mie: 0x00000000 mtvec: 0x00000000 mscratch: 0x00000000 mepc: 0x00000000 mcause: 0x00000000 mtval: 0x00000000 mip: 0x00000000 mtinsr: 0x00000000 mtval2: 0x00000000 mcycle: 0x00000009 minstret: 0x00000008
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到 R4 和 R6 中的加法运算结果

使用 ``--dump-cache-stats`` 查看 Cache 信息

```bash
$ qtrvsim_cli --asm --dump-cache-stats sum2vars.S
Cache statistics report:
i-cache:reads: 9
i-cache:hit: 0
i-cache:miss: 0
i-cache:hit-rate: 0.000
i-cache:stalled-cycles: 81
i-cache:improved-speed: 100.000
d-cache:reads: 2
d-cache:hit: 0
d-cache:miss: 0
d-cache:hit-rate: 0.000
d-cache:stalled-cycles: 36
d-cache:improved-speed: 100.000
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到 Cache 的读写，以及命中率等信息

使用 ``--dump-cycles`` 查看处理器运行周期

```bash
$ qtrvsim_cli --asm --dump-cycles sum2vars.S
Machine state report:
cycles: 9
stalls: 0
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

可以看到一共 9 个周期完成程序的运行

### 存储器状态

使用 ``--dump-range`` 和 ``--load-range`` 导出和载入存储器数据

从之前的输出可以看到，三个变量的实际物理地址为 1024 、 1028 和 1032 ，故这里演示使用 ``--dump-range`` 参数导出从 1000 开始长度为 64 字节一共 16 个字的数据的内存数据

```bash
$ qtrvsim_cli --asm --dump-range 1000,64,dump.txt sum2vars.S
$ cat dump.txt
0x00000000
0x00000000
0x00000000
0x00000000
0x00000000
0x00000000
0x0000bf24
0x00005678
0x000068ac
0x00000000
0x00000000
0x00000000
0x00000000
0x00000000
0x00000000
0x00000000
```

可以清晰看到 ``sw`` 指令写入内存物理地址分别为 1024 和 1032 的数据。这通常在有大量数据需要处理的情况下比较实用

### 处理器错误监视

使用 ``--expect-fail`` 参数期望程序出现处理器陷阱，否则报错

```bash
$ qtrvsim_cli --asm --expect-fail sum2vars.S
Machine state report:
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
$ echo $?
0
```

可以看到返回值变成了 0

使用 ``--fail-match`` 参数在发生该陷阱时退出执行。尽管帮助信息中描述了四种，但是其中三种没有正常执行

```bash
$ qtrvsim_cli --asm --fail-match I sum2vars.S
Machine state report:
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
$ qtrvsim_cli --asm --fail-match A sum2vars.S
Unknown fail condition: A
Machine state report:
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
$ qtrvsim_cli --asm --fail-match O sum2vars.S
Unknown fail condition: O
Machine state report:
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
$ qtrvsim_cli --asm --fail-match J sum2vars.S
Unknown fail condition: J
Machine state report:
Machine trapped: UnsupportedInstruction: Instruction with following encoding is not supported: 0
```

### Cache 模式

使用 ``--d-cache`` 和 ``--i-cache`` 参数更改 Cache 模式

### 存储器存取时间

使用 ``--read-time`` 、 ``--write-time`` 和 ``--burst-time`` 修改存储器存取实际消耗的周期，但是实际在五级流水线模式下并没有发现 ``lw`` 和 ``sw`` 消耗的时钟周期有所变化

### 延迟槽

使用 ``--no-delay-slot`` 禁用延迟槽。

### 操作系统模拟相关

``--serial-in`` 、 ``--serial-out`` 、 ``--os-emulation`` 、 ``--std-out`` 和 ``--os-fs-root`` 提供了一些便于较大型程序模拟的功能

KevinMX/qtrvsim test

简介

发行版

贡献者

近期动态

KevinMX/qtrvsim test .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

KevinMX/qtrvsim test