Docker - YatCPU 的 Docker 环境配置

YatCPU (Yet another toy CPU，逸芯) 是一款开源、开发中的教学用 RISC-V 处理器，基于 Chisel 硬件设计语言实现，并用于中山大学 (Sun Yat-sen University) 计算机学院冯班组成原理实验课程的教学。但笔者在配置对应的开发环境时遇到很多阻碍，经过一段时间的摸索和自行尝试过后，笔者决定对原文档中的 Docker 环境配置部分做一些补充，YatCPU原环境配置文档链接在此

YatCPU 的 Docker 环境配置

Docker 是什么

Docker 是一个应用打包、分发、部署的工具
你也可以把它理解为一个轻量的虚拟机，它只虚拟你软件需要的运行环境，多余的一点都不要，
而普通虚拟机则是一个完整而庞大的系统，包含各种不管你要不要的软件。

跟普通虚拟机的对比

特性	普通虚拟机	Docker
跨平台	通常只能在桌面级系统运行，例如 Windows/Mac，无法在不带图形界面的服务器上运行	支持的系统非常多，各类 windows 和 Linux 都支持
性能	性能损耗大，内存占用高，因为是把整个完整系统都虚拟出来了	性能好，只虚拟软件所需运行环境，最大化减少没用的配置
自动化	需要手动安装所有东西	一个命令就可以自动部署好所需环境
稳定性	稳定性不高，不同系统差异大	稳定性好，不同系统都一样部署方式

打包、分发、部署
打包：就是把你软件运行所需的依赖、第三方库、软件打包到一起，变成一个安装包
分发：你可以把你打包好的“安装包”上传到一个镜像仓库，其他人可以非常方便的获取和安装
部署：拿着“安装包”就可以一个命令运行起来你的应用，自动模拟出一摸一样的运行环境，不管是在 Windows/Mac/Linux。

如果你不知道什么是 Docker，可以直接跳过这一节，按照下面的 Windows 或 Linux/WSL 配置方法在本机进行配置；也可以选择自行去学习 Docker 的内容，详情可以参考这篇博客

拉取 YatCPU 镜像

该方法适用于 Windows、Linux 和 macOS 系统。

首先到 Docker 官方网站 选择并下载你使用的操作系统所对应的安装包，按照安装指南配置好 Docker。Docker 环境中含有 Scala 开发环境以及 Verilator 仿真器，但不包含 Vivado。如果你不需要烧板，那么使用 Docker 环境就可以完成所有实验以及软件测试了。

作为 Docker 的使用者，我们只需要运行：

docker run -it --rm howardlau1999/yatcpu
sbt test

Docker 就会自动下载我们准备好的镜像并运行容器。如果成功执行，你会看到类似这样的输出。

[success] Total time: 385 s (06:25), completed Dec 15, 2021, 8:45:25 PM

挂载本地目录

使用 Docker 运行后，我们改了项目代码不会立刻生效，需要重新 build 和 run，很是麻烦。

容器里面产生的数据，例如 log 文件，数据库备份文件，容器删除后就丢失了。
目录挂载解决以上问题

Docker 中的 YatCPU 代码可能不是最新版，且容器结束运行之后所有修改都将丢失，如果你需要完成实验，需要先将代码仓库克隆到本机，然后在运行 Docker 容器时挂载本机目录，直接把宿主机目录映射到容器内，适合挂代码目录和配置文件。Docker 的容器部分文件系统会直接创建在宿主机，所以删除或重启容器不会丢失容器数据

git clone --recursive https://github.com/howardlau1999/yatcpu
docker run -it --rm -v {此处填 yatcpu 在宿主机上的存储路径}:/root/yatcpu howardlau1999/yatcpu

按照这种方法在容器中所做的修改将保存到本机文件夹，反之同理。你可以把上述内容打包成一个 .bat 脚本，可以便捷启动

文件资源与运行环境分离

文件资源：文件资源是指工程项目在宿主机的物理表现形式

运行环境：运行环境是指工程项目运行时所必要的一些配套资源，比如编译器、解释器环境

通过前文的目录挂载，目前 YatCPU 的文件资源是存放在宿主机上，运行环境在 Docker 的镜像中，二者是分开的。所以当我们想要运行我们的工程项目时，我们需要在 Docker 提供的容器中运行；当我们需要修改工程项目的代码时，我们可以直接在本地更改

于是我们现在就可以在本地顺手的 IDE(比如 VScode) 上来做代码编辑，需要运行时就在 Docker 提供的运行环境中操作

因为运行环境存放在 Docker 提供的容器中，所以在本地无法正常运行 YatCPU 是预期行为

Chisel Bootcamp 环境配置

Chisel 是什么
Chisel 是 Scala 语言的一个库，可以由 Scala 语言通过 import 引入。
Chisel 编程可以生成 Verilog 代码或 C++ 仿真代码，是目前 YatCPU 的主要使用语言。

Chisel-Bootcamp是什么
Chisel-Bootcamp 是 Github 上的一个 Chisel 教程，包含了基于 Jupytor 的 Chisel 教学，这篇文章讲一下基于 Docker 来配置 Bootcamp 环境，主要参考资料是 Bootcamp 在 github 上的安装教程

启动命令

确保你已经启动 Docker 引擎，在终端输入以下内容：

docker run -d --name chisel-jupyter -it --rm -p 8888:8888 ucbbar/chisel-bootcamp
docker exec -d --user root -it chisel-jupyter chown -R bootcamp:bootcamp /coursier_cache

你可以把上述内容打包成一个 .bat 脚本，可以便捷启动

---