From 467398b679236f3fca57530e989cd2454f635fbc Mon Sep 17 00:00:00 2001
From: wangfiox <wangfiox@gmail.com>
Date: Mon, 27 May 2024 15:48:41 +0800
Subject: [PATCH]     :pencil:

---
 docs/unofficial-lab-env/comp-organ-lab2.md | 112 +++++++++++++++------
 1 file changed, 82 insertions(+), 30 deletions(-)

diff --git a/docs/unofficial-lab-env/comp-organ-lab2.md b/docs/unofficial-lab-env/comp-organ-lab2.md
index 66856b0..2c28bc3 100644
--- a/docs/unofficial-lab-env/comp-organ-lab2.md
+++ b/docs/unofficial-lab-env/comp-organ-lab2.md
@@ -1,6 +1,6 @@
 # 计算机组成原理实验 2 环境指南（非官方）
 
-以下指南适合有 linux 环境的同学使用。
+以下指南适合有 linux/mac 环境的同学使用。
 
 笔者心态：对 verilog 感到不适，并且想折腾一些花样。
 
@@ -41,6 +41,8 @@ sudo zypper in -t pattern devel_C_C++
 
 如果配置环境过程中出现“command not found.”可能是有依赖的工具没装，此时可以利用搜索引擎。
 
+mac 需要安装 homebrew 作为包管理器，请查阅: https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/
+
 ## 安装 bison 和 flex
 
 bison 和 flex 是 gnu 提供的两个语法解析工具。
@@ -55,48 +57,82 @@ sudo dnf install bison flex
 sudo pacman -Sy bison flex
 # opensuse
 sudo zypper in bison flex
+# mac
+brew install bison flex
 ```
 
 ## 安装 verilator
 
-为什么需要手动安装？使用包管理器安装 verilator 有时候并不会携带 `.cmake` 文件，导致 cmake 中 find_package 找不到 verilator
+使用包管理器安装
 
 ```sh
-# 先 cd 到一个文件夹中，推荐 cd 到 ~/Downloads
+# debian/ubuntu
+sudo apt install verilator
+# fedora/centos
+sudo dnf install verilator verilator-devel
+# arch
+sudo pacman -Sy verilator
+# mac
+brew install verilator
+```
+
+但是有一些 linux 的发行版，他会将包拆的比较奇怪，导致没法找到 `verilated.mk` 之类的情况发生。亦或者是版本比较老，则可以使用编译安装
+
+```sh
+# 先 cd 到一个文件夹中，推荐 cd 到 $HOME/Downloads
 git clone https://github.com/verilator/verilator
 cd verilator
 autoconf # 生成 ./configure 文件
 ./configure --prefix=$HOME/app/verilator # 配置 makefile 和安装路径
 make -j `nproc` # 多核编译
-make install  # 这会安装到 /usr 中
-echo 'export PATH=$PATH:$HOME/app/verilator/bin' >> .bashrc # 追加环境变量
+make install  # 这会安装到 $HOME/app/verilator 中
+echo 'export VERILATOR_ROOT=$HOME/app/verilator' >> .bashrc # 追加环境变量
 ```
 
-如果想要其他支持，请查阅 verilator 的安装文档 https://verilator.org/guide/latest/install.html#git-quick-install
+如果想要其他支持，请查阅 verilator 的安装文档 https://verilator.org/guide/latest/install.html
 
-( 因为 verilator 在编译的时候，需要使用 gnu 方言，因此推荐使用 linux )
+verilator 在编译过程中，需要用到 gnu 方言，因此推荐使用 linux。当然 mac 下的`brew install`就已经可以正常工作了。
 
 ## 安装 sdkman
 
+注意，并不一定要安装 sdkman 。sdkman 是一个用于管理 java 相关开发环境的软件。
+如果我们发行版的包管理器可以顺利安装 java, scala@2.12.13, sbt ，那么实际上也不需要 sdkman。
+
+```sh
+# arch
+paru sbt
+sudo pacman -Sy openjdk
+paru scala_2.12
+# fedora
+sudo dnf install sbt openjdk scala-2.12
+# mac
+brew install sbt openjdk scala@2.12
+```
+
+注意，笔者没有查到 ubuntu/debian/opensuse/centos 可以使用包管理安装 sbt 的方式。
+因此，推荐通过 sdkman 安装 sbt 。当然，scala 和 openjdk 是可以通过包管理器安装的。
+
+可以通过下面这个命令安装
+
 ```sh
 curl -s "https://get.sdkman.io" | bash
 ```
 
-安装过程中，注意看提示，会要求在安装完成后配置环境变量
+安装过程中，注意看提示，会要求在安装完成后配置环境变量。
 
-## 安装 java
+### 使用 sdkman 安装 java
 
 ```sh
 sdk install java
 ```
 
-## 安装 scala 2.12.13
+### 使用 sdkman 安装 scala 2.12.13
 
 ```sh
 sdk install scala 2.12.13
 ```
 
-## 安装 sbt
+### 使用 sdkman 安装 sbt
 
 sbt 是 scala 项目的构建软件
 
@@ -111,8 +147,8 @@ sdk install sbt
 sudo apt install gtkwave
 # fedora/centos
 sudo dnf install gtkwave
-# arch/manjaro
-paru gtkwave
+# arch
+sudo pacman -Sy gtkwave
 # opensuse
 sudo zypper in gtkwave
 # windows
@@ -121,13 +157,39 @@ winget install gtkwave
 brew install gtkwave
 ```
 
-如果 windows/mac 作为宿主系统，应该是在 windows/mac 中安装 gtkwave，然后在 windows 打开 `.vcd` 文件。
+如果 windows/mac 作为宿主系统，应该是在 windows/mac 中安装 gtkwave，然后在 windows/mac 打开 `.vcd` 文件。
 
-但是 mac 实际上使用 gtkwave 会有点问题（无法双击打开）。但是可以在 shell 中 `gtkwave <.vcd>`打开。
+但是 mac 实际上使用 gtkwave 会有点兼容问题（无法双击打开）。但是可以在 shell 中 `gtkwave <.vcd>`打开。
 
 如果是 ssh 连接的 linux，可以使用 CyberDuck 或者是 MountainDuck（付费）或者是 sshfs 挂载目录，然后在 宿主机上 `gtkwave <.vcd>` 或者是双击打开。（笔者就是用的这种方式）
 
-## 创建 chisel 项目
+## chisel(scala) IDE 的选择
+
+chisel 只是 scala 中的一个库。因此，只要 IDE 能支持 scala ，那么自然也是支持 chisel 了。
+但是一些 IDE 如 vscode/IDEA 会对 chisel 语法有更加好的 highlight 支持。
+
+经观察：对于稍微大一些的 chisel 项目 (小学期级别), VSCode + Metals 会很卡, 建议使用 JetBrain IDEA
+
+### vscode 对 chisel(scala) 的支持
+
+下面是笔者使用的 vscode 插件
+
+- Chisel Syntax
+- Scala (Metals)
+- Scala Snippets
+- Scala Syntax (official)
+
+### vscode 对 chisel(scala) 的支持
+
+下面是笔者使用的 JetBrain IDEA 插件
+
+- Scala
+
+## example
+
+下面这个例子可以在：https://github.com/KINGFIOX/chisel-verilator-example 这里找到
+
+### 创建 chisel 项目
 
 chisel 是 scala 的一个库并且目前为止并没有一个真正的 chisel IDE。我们可以通过官方的 chisel-template 创建我们的项目。
 
@@ -135,11 +197,7 @@ chisel 是 scala 的一个库并且目前为止并没有一个真正的 chisel I
 git clone https://github.com/chipsalliance/chisel-template.git <my-chisel-project>
 ```
 
-然后在 vscode 中打开我们的 chisel 就行了。当然也可以使用 IDEA 等。
-
-经观察：对于稍微大一些的 chisel 项目 (小学期级别), VSCode + Metals 会很卡, 建议使用 JetBrain IDEA
-
-## 编写 chisel 代码
+### 编写 chisel 代码
 
 chisel-template 项目下天然的提供了一个 GCD 硬件 module 。
 
@@ -227,16 +285,10 @@ module GCD(
 endmodule
 ```
 
-这里是 scala 语法的教程: https://docs.scala-lang.org/zh-cn/
-
-## vscode 对 chisel(scala) 的支持
-
-- Chisel Syntax
-- Scala (Metals)
-- Scala Snippets
-- Scala Syntax (official)
+- 这里是 scala 教程： https://docs.scala-lang.org/zh-cn/
+- 这里是 chisel 教程： https://www.chisel-lang.org/docs/cookbooks/cookbook
 
-## 使用 verilator c++ 调试 chisel 生成的 verilog
+### 使用 verilator c++ 调试 chisel 生成的 verilog
 
 下面是一个 c++ 下的 testbench