# oscpu-framework

**Repository Path**: RV4Kids/oscpu-framework

## Basic Information

- **Project Name**: oscpu-framework
- **Description**: `一生一芯`开发框架早期笔记分支，chisel块曾有bug落后另一分支，已修复，verilog块有一些起步demo，注重对原版的注释，现【保留可能适合科班高手使用的简约difftest输出】作为异步调试分支对比另一【difftest汉化友善冗余输出中文的 https://gitee.com/rexiyz/oscpu-framework-soc】分支学习用，建议新手都重视
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 2021
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 14
- **Created**: 2024-12-03
- **Last Updated**: 2024-12-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

本库是原版注释分支（如果有些地方没注释看不懂请去看另一分支）。

助教和同学们用的vscode的搜索功能有bug(已告知微软员工，待修复)，有些东西是搜不出来的，建议使用命令行搜索，命令类似
```shell
#搜索目录里的文本
grep -r 'rst' libraries/difftest/
#搜索文件名
sudo find -name 'Vrvcpu.h'
```

`一生一芯（ysyx）`开发框架（即oscpu-framework）早期中文注释原版的笔记分支： https://gitee.com/am_1/oscpu-framework （chisel块曾有bug落后另一分支，已修复，verilog块有一些起步demo，注重对原版的注释），现【保留可能适合科班高手使用的简约difftest输出】作为异步调试分支。

请对比另一【difftest汉化友善冗余输出中文、提高soc等调试易用性的
https://gitee.com/rexiyz/oscpu-framework-soc 】分支学习用，建议新手对两个分支都重视。

注意：源码注释和输出引用的书籍（包括其它riscv的书籍或文章）处于创作早期阶段，时而引发歧义，请务必仔细阅读我两个分支的注释和输出中对书籍描述逻辑的修正，如果不重视我两个分支的注释和输出对书籍的刊误，只看书籍和代码，容易引起逻辑混乱或不知道如何下手，我对这个教学项目的二次开发目的就在于提高教学的用户体验，让学生学得更顺畅，打通知识之间的联系，而不是无止境搜索越搜索逻辑分歧越来越多，验证逻辑的代码最后指数性上升影响基础知识的入门和巩固。

例如注释我会写成“rs1字段指向的寄存器” 而不是书籍里的“rs1寄存器”，因为rs1其实不是寄存器，而是rs1这个字段用编码指向寄存器，暂时看不懂也没关系，运行我的代码跟着输出和代码注释浪，学得肯定比其它方式快、稳、扎实，要不言简意赅的视频和手册对于新手可能看了好几遍也不知道是什么意思，因为学习周期太长，粒度够细的题不够数量，看到手册又忘了前面看了好几次的视频的知识点，视频没有提供粒度足够细的习题，去补充这个视频的前置知识，同样练很久也忘记了这个视频的知识点，前中后的知识要么提供粒度足够细数量足够多的习题，要么就要让做大作业时能通过手册和demo打好前中后的基础。

再例如在oscpu目录下运行./soc.sh 提示
Interface check failed. Check build_test/cpu-check.log for more details.
2021-11-20 15:10:37,970 - cpu-check.py[line:121] - ERROR: you need to check code in: clock 这样的提示并不是指 projects/soc/vsrc/ysyx_210686.v 的121行有错误，我的这一行并没有clock，即使我去其它地方消掉clock报错了，可还有好多报错，全部都显示在121行，但都不在ysyx_210686.v的121行，而是cpu-check.py的121行logging出来的，建议logging可以再思路清晰一些，例如提醒是ysyx_210686.v缺失顶层模块clock，因为这个文件其他clock没错，去check应该属于错误提示吧，再check也没错，而是应该提示追加顶层模块的clock，然后再logging出“CPU接口命名规范”的链接，而不是soc库的主页，其实好多程序员都不知道“CPU接口命名规范”就是“信号”，没经过科班培训他们可能会把任何输出都猜测成信号。建议类似这样完善调试器输出，让开发者可以遇到大部分bug都能进入知识图谱了解工具链的api，开箱即用，这样才有望体验接近流行编程语言的编译器、解释器。

理想状态就是至少difftest的输出要能让程序员去索引手册时没有歧义，手册对于【寄存器】、【指令】要有能【完整正确运行】且有【详细注释】的【代码demo】，然后配上verilog和chishel手册，同样做到上面描述的difftest+riscv手册的成熟级别，这样这个教学工具链才有望达到现在编程语言top版上的流行语言的教程成熟程度，这样大量人才入门才比较有望，入门的人多了，才更有希望有更多人来做后面的改进工作吧。

也就是riscv那两本中文手册的英文版有巨大的改进空间，也许我们可以提前在中文版里改进，英文和翻译版感觉那是给懂写intel和arm指令的人看的，对于不懂写intel和arm指令的外专业程序员，这两本手册的简短成了劣势，每看一段都要不断搜索理解里面的关键字，但是又没有详细的官方权威版，网上懂基础和愿意讲清楚基础的资料也很少，这两个分支就是致力于解决以上问题。

在verilog的.v文件里：
trap <= 1; //这样写就全pass了

现在：

在/home/lee/ysyx/verilog/oscpu/projects/chisel_cpu_diff/src/main/scala/bak_difftest/src/main/scala下删除了多余的Difftest.scala，修复了下面的chisel_cpu_diff编译时出错，几个.scala文件的位置与https://gitee.com/rexiyz/oscpu-framework-soc 稍有不同不影响编译

早期：

似乎在ca5faeea236bd2849e6e3289842b007220dc99ca附近即合并我修复的chisel_cpu_diff和中科院修复的有冲突，造成chisel_cpu_diff编译时出错？chisel_cpu_diff进一步的开发暂时移至https://gitee.com/rexiyz/oscpu-framework-soc ，这边仍继续开发其他部分
把所有文件上传下载可加速编译，早期上传了一些，现在暂时不上传部分build、bulid_test、obj_dir、logs
```shell
# 从大到小显示文件夹大小，包括隐藏文件
du -sh * .[^.]* | sort -nr
# 找到要删除的目录（文件夹）
lee@lee-pc:~/ysyx/verilog/oscpu$ find -name build
./libraries/NEMU/tools/kconfig/build
./libraries/NEMU/tools/kconfig/build/obj-conf/build
./libraries/NEMU/tools/fixdep/build
./libraries/NEMU/build
./libraries/NEMU/resource/softfloat/repo/build
./libraries/NEMU/resource/softfloat/build
./libraries/DRAMsim3/build
#上面几行少改动的暂时先不删
./projects/counter/build
./projects/chisel_cpu_diff/build
./projects/cpu/build
./projects/cpu_diff/build
./projects/cpu_axi_diff/build

lee@lee-pc:~/ysyx/verilog/oscpu$ find -name build_test
./projects/counter/build_test
./projects/cpu/build_test

lee@lee-pc:~/ysyx/verilog/oscpu$ find -name obj_dir
./projects/test_our/obj_dir
./projects/make_hello_c/obj_dir
./projects/make_tracing_c/obj_dir
./projects/make_protect_lib/obj_dir

lee@lee-pc:~/ysyx/verilog/oscpu$ find -name logs
./libraries/NEMU/resource/softfloat/repo/.git/logs
./.git/logs
./.git/modules/libraries/NEMU/logs
./.git/modules/libraries/difftest/logs
./.git/modules/libraries/DRAMsim3/logs
./.git/modules/libraries/DRAMsim3/modules/ext/SuperLU_MT_3.1/logs
#上面几行git的先不删
./projects/make_tracing_c/logs
./projects/make_protect_lib/logs
#一顿操作写了脚本并运行，脚本里有注释
chmod 755 fix_git_index.sh
./fix_git_index.sh
```

用于合并我开发的版本和中科院的版本的脚本
```shell
./git_merge.sh
```

# oscpu-framework

这是一个基于`verilator`的`RISC-V`CPU开发仿真框架。  

开发前请在`myinfo.txt`文件中填写报名`一生一芯`时的学号和自己的姓名。例如：

```
ID=202100001
Name=张三
```

# 开发环境

操作系统：[Linux Ubuntu v20.04](https://ubuntu.com/download/desktop)   ubuntu 21 也可以,在下面的一键下载安装开发环境脚本里改一下版本判断就好

开发软件：[verilator](https://verilator.org/guide/latest/)、[gtkwave](http://gtkwave.sourceforge.net/)、[mill](https://github.com/com-lihaoyi/mil)

可以使用下面的命令一键安装搭建开发环境。

```shell
# 选择使用verilog语言开发
wget https://gitee.com/oscpu/oscpu-env-setup/raw/master/oscpu-env-setup.sh && chmod +x oscpu-env-setup.sh && ./oscpu-env-setup.sh -g && rm oscpu-env-setup.sh
# 选择使用chisel语言开发
wget https://gitee.com/oscpu/oscpu-env-setup/raw/master/oscpu-env-setup.sh && chmod +x oscpu-env-setup.sh && ./oscpu-env-setup.sh -g -c && rm oscpu-env-setup.sh
```

# 获取代码

```shell
# 从gitee上克隆代码
git clone --recursive -b 2021 https://gitee.com/am_1/oscpu-framework.git oscpu
```

如果子仓库克隆失败，可在`oscpu`目录下使用下面的命令重新克隆子仓库。

```shell
git submodule update --init --recursive
```

参与`一生一芯`还需要设置git信息。

```shell
# 使用你的编号和姓名拼音代替双引号中内容
git config --global user.name "2021000001-Zhang San"
# 使用你的邮箱代替双引号中内容
git config --global user.email "zhangsan@foo.com"
```

# 例程

`projects`目录用于存放工程文件夹，`projects`目录下的几个例程可用于了解如何基于`verilator`和`香山difftest框架`来开发仿真CPU。你可以在该目录下创建自己的工程。工程目录结构如下：

```shell
.
├── build.sc		# 存放chisel编译信息的文件，选择chisel语言时需要该文件
├── csrc			# 存放仿真c++源码的文件夹，接入香山difftest框架时不需要该文件夹
├── src				# 存放chisel源码的文件夹，选择chisel语言时需要该文件夹
└── vsrc			# 存放verilog源码的文件夹，选择verilog语言时需要该文件夹
```

我们提供了脚本`build.sh`用于自动化编译、仿真和查看波形。下面是`build.sh`的参数说明，也可在oscpu目录下使用`./build.sh -h`命令查看帮助。

```shell
-e 指定一个例程作为工程目录，如果不指定，将使用"cpu"目录作为工程目录
-b 编译工程，编译后会在工程目录下生成"build"(difftest)或"build_test"子目录，里面存放编译后生成的文件
-t 指定verilog顶层文件名，如果不指定，将使用"top.v" 或"SimTop.v"(difftest)作为顶层文件名，该选项在接入difftest时无效
-s 运行仿真程序，即"build/emu"程序，运行时工作目录为"build"(difftest)或"build_test"子目录
-a 传入仿真程序的参数，比如：-a "1 2 3 ......"，多个参数需要使用双引号
-f 传入c++编译器的参数，比如：-f "-DGLOBAL_DEFINE=1 -ggdb3"，多个参数需要使用双引号，该选项在接入difftest时无效
-l 传入c++链接器的参数，比如：-l "-ldl -lm"，多个参数需要使用双引号，该选项在接入difftest时无效
-g 使用gdb调试仿真程序，该选项在接入difftest时无效
-w 使用gtkwave打开工作目录下修改时间最新的.vcd波形文件
-c 删除工程目录下编译生成的"build"文件夹
-d 接入香山difftest框架
-m 传入difftest框架makefile的参数，比如：-m "EMU_TRACE=1 EMU_THREADS=4"，多个参数需要使用双引号
-r 使用给定的测试用例集合进行回归测试，比如：-r "case1 case2"，该选项要求工程能够接入difftest
```

## 编译和仿真 

### counter

`examples/counter`目录下存放了4位计数器的例程源码main.cpp.old和top.v.old,把.old去掉,可以使用下面的命令编译和仿真查看波形。

```shell
./4rexi_shell.sh
```

如果`verilator`安装正确，你会看到下面的输出

```shell
Simulating...
Enabling waves ...
Enter the test cycle:
```

输入测试周期数后仿真程序退出，并在`projects/counter/build_test/`路径下生成`.vcd`波形文件,并打开。

新的main.cpp和top.v也可运行,供参考分析,也用以下方法运行
```shell
./4rexi_shell.sh
```

### project

https://veripool.org/guide/latest/overview.html
用网页在mac复制代码有缩进，下面的pdf没有
`projects`目录有verilator_doc.pdf

### test_our

`projects/test_our`目录

```shell
./run.sh
```

### 其他verilator examples，官方例子有逐行解释代码，超赞

```shell
whereis verilator
cd /usr/share/verilator/examples
cd make_hello_c/
clear && make
cd ../make_tracing_c
clear && make
#经过稍微修改后,将项目复制到本git库
cp -r make_hello_c ~/ysyx/verilog/oscpu/projects/make_hello_c
cd ~/ysyx/verilog/oscpu/projects/make_hello_c
make
cp -r make_tracing_c ~/ysyx/verilog/oscpu/projects/make_tracing_c
cd ~/ysyx/verilog/oscpu/projects/make_tracing_c
./run.sh
cp -r make_protect_lib ~/ysyx/verilog/oscpu/projects/make_protect_lib
cd ~/ysyx/verilog/oscpu/projects/make_protect_lib
make
```

### cpu

`projects/cpu`目录下存放了`verilog`版本单周期`RISC-V`CPU例程源码和详细注释，源码实现了`RV64I`指令`addi`。可以使用下面的命令编译和仿真。

```shell
./build.sh -b -t rvcpu.v -s
./cpu.sh
```

输入`inst.bin`和回车后程序结束运行，并在`projects/cpu/build_test/`路径下生成`.vcd`波形文件。其中`inst.bin`为`bin`目录下的一个`RISC-V`测试程序，里面存放了3条`addi`指令。

### cpu_diff

`projects/cpu_diff`目录下存放了接入`香山difftest框架`的`verilog`版本单周期`RISC-V` CPU例程源码，源码实现了`RV64I`指令`addi`。关于`香山difftest框架`的详细介绍，可参考[讲座-Difftest 处理器验证方法介绍](https://oscpu.github.io/ysyx/events/events.html?EID=2021-07-17_Difftest)，接口说明可参考[difftest_api.md](./doc/difftest_api.md)和[chisel_difftest.md](./doc/chisel_difftest.md)。可以使用下面的命令编译和仿真。

```shell
# 编译仿真
./build.sh -e cpu_diff -d -b -s -a "-i inst_diff.bin"
# 编译仿真，并从CPU上报至difftest的时钟周期0开始输出波形
./build.sh -e cpu_diff -d -b -s -a "-i inst_diff.bin --dump-wave -b 0" -m "EMU_TRACE=1"
# 编译仿真，并从CPU上报至difftest的时钟周期0开始输出波形至wave.vcd文件
./build.sh -e cpu_diff -d -b -s -a "-i inst_diff.bin --wave-path=wave.vcd --dump-wave -b 0" -m "EMU_TRACE=1"
```

仿真程序运行后，终端将打印绿色的提示内容`HIT GOOD TRAP at pc = 0x8000000c`。说明程序运行到自定义的`0x6b`指令，并且此时存放错误码的`a0`寄存器的值为0，即程序按照预期结果成功退出。关于`0x6b`自定义指令作用，可参考[讲座-AM运行环境介绍](https://oscpu.github.io/ysyx/events/events.html?EID=2021-07-13_AM_Difftest)。如果指定输出波形，将在`projects/cpu_diff/build/`路径下生成`.vcd`波形文件。

### cpu_axi_diff

`projects/cpu_diff`目录下存放了通过`AXI总线`接入`香山difftest框架`的`verilog`版本单周期`RISC-V`CPU例程源码，源码实现了`RV64I`指令`addi`和`AXI总线`读逻辑。可以使用下面的命令编译和仿真。

```shell
./build.sh -e cpu_axi_diff -d -s -a "-i inst_diff.bin --dump-wave -b 0" -m "EMU_TRACE=1 WITH_DRAMSIM3=1" -b
./build.sh -e cpu_axi_diff -d -s -a "-i inst_diff.bin --wave-path=wave.vcd --dump-wave -b 0" -m "EMU_TRACE=1 WITH_DRAMSIM3=1" -b
```

### chisel_cpu_diff

`projects/chisel_cpu_diff`目录下存放了接入`香山difftest框架`的`chisel`版本单周期`RISC-V` CPU例程源码，源码实现了`RV64I`指令`addi`。可以在该目录里使用下面的命令编译和仿真。

```shell
./20210686hack01.sh
查看源码行数
./src/main/scala/line.sh
`projects/cpu_diff`目录下存放了接入`香山difftest框架`的`chisel`版本单周期`RISC-V` CPU例程源码，源码实现了`RV64I`指令`addi`。可以使用下面的命令编译和仿真。

```shell
./build.sh -e chisel_cpu_diff -d -s -a "-i inst_diff.bin" -m "EMU_TRACE=1" -b
```

### soc

`projects/soc`目录下存放了接入`ysyxSoC`的示例程序。源码中只有一个占位符，能够通过编译但不能正常运行。

要使用该框架，需要先按照 [ysyx SoC 的 readme](https://github.com/osCPU/ysyxsoc) 完成 `命名规范` 和 `CPU 内部修改` 两个步骤，得到 `ysyx_21xxxx.v`，随后放入 `projects/soc/vsrc/` 中。此后，执行下面的命令将会根据 `myinfo.txt` 中的 ID 自动 对代码进行规范检查、集成到 `soc` 并运行指定的程序。`ysyxSoC` 中附带的例程会被自动软连接至 `build` 目录下，仿真时可以快速使用。

```bash
./build.sh -e soc -b -s -y -v '--timescale "1ns/1ns" -Wno-fatal --trace' -a "-i ysyxSoC/flash/hello-flash.bin --dump-wave"
```

由于无法直接使用 `difftest` 框架，暂时只支持少量参数。
```bash
$ ./emu -h
Usage: ./emu [OPTION...]

  -i, --image=FILE           run with this image file
      --dump-wave            dump waveform when log is enabled
  -b, --log-begin=NUM        display log from NUM th cycle
  -e, --log-end=NUM          stop display log at NUM th cycle
  -h, --help                 print program help info
```

## 查看波形

在`oscpu`目录下使用命令可以通过`gtkwave`查看输出的波形，其中`xxx`表示例程名。

```shell
# 未接入difftest
./build.sh -e xxx -w
# 接入difftest
./build.sh -e xxx -d -w
```

# 测试用例

`bin`目录下存放了`一生一芯`[基础任务](https://oscpu.github.io/ysyx/wiki/tasks/basic.html)需要使用的测试用例，具体说明详见[一生一芯基础任务测试用例说明](./bin/README.md)。

# 回归测试

一键回归测试用于自动化测试给定的测试用例集合，可以通过以下命令对CPU进行一键回归测试。该命令会将`bin`目录下指定子目录中所有`.bin`文件作为参数来调用接入了`香山difftest框架`的仿真程序，其中`xxx`表示例程名。

```shell
# 未接入AXI总线的情况下使用"non-output/cpu-tests"和"non-output/riscv-tests"目录下的bin进行回归测试
./build.sh -e xxx -b -r "non-output/cpu-tests non-output/riscv-tests"
例如:
./chisel.sh
# 接入AXI总线的情况下使用"non-output/cpu-tests"和"non-output/riscv-tests"目录下的bin进行回归测试
./build.sh -e xxx -b -r "non-output/cpu-tests non-output/riscv-tests" -m "WITH_DRAMSIM3=1"	
例如:
./verilog_cpu_axi_diff.sh
```

通过测试的用例，将打印`PASS`。测试失败的用例，打印`FAIL`并生成对应的log文件，可以查看log文件来调试，也可以另外开启波形输出来调试。

# 代码上传

在本框架中接入`ysyxSoC` 并完成所有测试后，可以开始代码上传流程。**上传前请确保所有触发器可复位。** 

1. 每次提交前，确保同步了最新的`oscpu-framework`仓库。
1. 每次提交前，重新接入总线后的回归测试，并将成功运行的截图文件`reg-testing.png`放置于`submit`目录下，截图中必须包含使用`date`命令输出的当前时间。
1. 每次提交前，重新运行正常模式的`rtthread-loader.bin`，并将成功运行的截图文件`rtthread-loader.png`放置于`submit`目录下，截图中必须包含使用`date`命令输出的当前时间。
1. 将`.v`代码里所有的宏加上`YSYX210xxx_`作为前缀，例如`define YSYX210001_PC_START  64'h80000000`。
1. 如果实现了`cache`，填写`doc`目录下的`cache规格.xlsx`并拷贝至`submit`目录下。
1. 根据[代码规范检查步骤](https://github.com/OSCPU/ysyxSoC/blob/master/ysyx/lint/README.md)填写`Verilator中Warning无法清理说明.xlsx`文件并拷贝至`submit`目录下。
1. 制作一份带数据流向的处理器架构图，并对图中各模块做简单说明，整理成`ysyx_21xxxx.pdf`文件并放置于`submit`目录下。
1. 创建自己的`gitee`开源仓库。
1. 进入`oscpu`目录下，运行`./submit.sh`，根据提示将代码上传至创建的`gitee`开源仓库。
1. 将自己仓库的`HTTPS`格式的`URL`(例如：`https://gitee.com/oscpu/oscpu-framework.git`)和学号发送给组内助教以完成第一次代码提交。后续提交只需要重新运行`./submit.sh`即可，无需通知助教。

后续提交不可修改cache规格，只能根据report反馈修复bug。SoC和后端团队将定期检查新提交的代码，进行综合和仿真测试，并将结果以日志报告的形式上传至ysyx_submit仓库，具体说明请参考[ysyx_submit仓库](https://github.com/OSCPU/ysyx_submit/)的说明文档。

# 扩展

[一生一芯官网](https://oscpu.github.io/ysyx/)

[会议汇总](https://oscpu.github.io/ysyx/events/)

[讲座回放](https://www.bilibili.com/video/BV1PU4y1V7X3)

[RISC-V Unprivileged Spec](https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMAFDQC/riscv-spec-20191213.pdf)

[RISC-V Privileged Spec](https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-privileged-20190608.pdf)

[cpu-tests](https://github.com/NJU-ProjectN/am-kernels)

[riscv-tests](https://github.com/NJU-ProjectN/riscv-tests)

[香山difftest框架](https://github.com/OpenXiangShan/difftest)

[NEMU](https://github.com/OpenXiangShan/NEMU)

[DRAMsim3](https://github.com/OpenXiangShan/DRAMsim3)

[AXI4 specification](http://www.gstitt.ece.ufl.edu/courses/fall15/eel4720_5721/labs/refs/AXI4_specification.pdf)