初學者適合: [使用Jupyter Notebook 建構Chisel環境](https://hackmd.io/@Ethan2339/B1XJWWGZ1x)

[TOC]

### 步驟 1: 安裝 WSL (Windows Subsystem for Linux)

1. **WSL**：

使用WLS原因是因為許多軟體透過Linux指令安裝較為方便快速。

在 Windows 上下載 WSL (Windows Subsystem for Linux): 開啟 PowerShell 並執行以下命令：

   wsl --install

WSL（Windows Subsystem for Linux）是 Windows 10 和 Windows 11 上的功能，允許在 Windows 上運行 **Linux 環境**，包括大部分 Linux 工具、命令行工具和應用程式，而無需使用虛擬機或雙系統。

2. **開啟電腦Bios虛擬機選項**:

**Step1.** Advanced（進階選項）
**Step2.** CPU Configuration（CPU 配置）
**Step3.** System Configuration（系統配置）


3. **重啟電腦**：
安裝完成後，系統會要求重新開機。重新開機後，開啟 WSL設定 Linux 用戶名稱和密碼。

4. **更新 WSL 及安裝必需的工具**：
打開 `WSL` 終端，確保系統和管理器是最新的：

   sudo apt update

   sudo apt install curl

### 步驟 2: 安裝 JDK 和 SBT

Chisel 是基於 Scala 的程式語言，所以需要安裝 **Java Development Kit (JDK)** 和 **SBT (Scala Build Tool)**：

1. **安裝 JDK**：
Chisel 和 Almond 核心需要 JDK，使用以下命令安裝 OpenJDK：

   sudo apt install openjdk-11-jdk //更新:6.5.0 使用 17 LTS

安裝後，確認 Java 是否正確安裝：

   java -version

2. **安裝 SBT**：
SBT 是 Scala 的構建工具，使用以下命令安裝：

   //建議逐行輸入
   echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
   curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x99E82A75642AC823" | sudo apt-key add
   sudo apt update
   sudo apt install sbt

確認 SBT 安裝成功：

   sbt sbtVersion

### 步驟 3: 安裝 VSCode 和擴展

1. **安裝 VSCode**：
可以從 [VSCode 官方網站](https://code.visualstudio.com/) 下載並安裝。

2. **安裝 Jupyter 擴展**：
在 VSCode 中，打開Extension Market (`Ctrl+Shift+X`)，搜尋 `Jupyter`，然後安裝擴展( Extension is enabled on WSL: Ubuntu )。

3. **安裝 Metals 擴展（Scala 支援）**：
安裝 `Metals` 擴展，這是 Scala 的語言伺服器，能夠提供程碼碼高亮、提示、自動完成等功能。打開Extension Market，搜尋 `Metals` 並安裝。
* SBT：編譯和執行 Scala 程式。
* Metals：提供開發時的輔助功能(即時語法檢查，智能程式碼補全，懸停顯示型別資訊，快速修復建議)。
4. **安裝 Scala Syntax 和Chisel Syntax語法擴展** :

### 步驟 4: 在 VSCode 中運行使用自己的Chisel 專案
1. **創建一個 Chisel 項目**：
到 [Chisel template](https://github.com/chipsalliance/chisel-template)下載基本環境資料檔案來測試自己是否可以成功運行Chisel，未來可以用來建構自己的Chisel專案。
2. **打開 VSCode**：
WSL環境中，在剛下載好範例的目錄底下用 VSCode 打開這個專案的資料夾：

   code .

### 步驟 5: SBT執行與測試
- **SBT 構建**：
(初次使用官方的template可以到 `main/src/scala/DecoupledGCD` 開啟GCD.scala進行環境測試)

   sbt run

   sbt test

### 步驟6: 安裝Verilator
最詳細的安裝步驟請參閱官方標準安裝流程，[點我](https://veripool.org/guide/latest/install.html)。
> [name=Ethan]


1. **切換不同版本的 Verilator**

有時編譯問題可能是特定於某個版本的。如果使用的是最新的開發版，可以考慮退回到一個較舊的穩定版來進行編譯。
例如：

    git checkout v4.200

2. **編譯**

源代碼編譯，圖片上有誤。

    make -j$(nproc) VERBOSE=1

### 進入專案步驟
1. 啟動WSL
2. 輸入卦載資料路徑 :

    ex: cd /mnt/c/Users/user/MyChisel2

3. 開啟VSCode

    code .

### 補充
* 使用sbt run 生成的Verilog導向新的資料夾

    sbt "runMain MyModule" > 1.v

* 避免生成的.v檔 夾雜不必要的log資訊可以使用以下命令，只保留error資訊。

    sbt -error "runMain MyModule" > 1.v

----
**Chisel 在 Windows 和 WSL 環境上的差異比較**

| 特性 | Windows 原生環境 | WSL |
|--------------------------|--------------------------------|-----------------------------|
| **Verilator 安裝** | 需要 Cygwin/MSYS2，安裝繁瑣 | `apt` 安裝簡單快捷 |
| **工具鏈設置** | 手動安裝，需額外設置環境變量 | Linux `apt` 安裝方便 |
| **Unix 工具的使用** | 受限，需要模擬環境支持 | 完整支持 Linux 工具鏈 |
| **文件系統兼容性** | NTFS 存在兼容性問題 | 支持 Linux 文件系統，兼容性好|
| **硬體模擬和驗證工具** | 安裝繁瑣，模擬工具性能一般 | Verilator、GTKWave 安裝簡單 |
| **命令行操作** | cmd/PowerShell 限制多 | bash 提供完整命令行體驗 |
| **編譯/運行性能** | 一般，受限於 NTFS 和 JVM | 性能接近 Linux 原生 |
| **IDE 支持** | 支援 IntelliJ IDEA、VSCode | VSCode Remote - WSL 支援流暢 |

:::spoiler
在 Windows 和 WSL (Windows Subsystem for Linux) 上使用 Chisel 以及硬體驗證工具時，兩者在環境設置、工具支持、性能以及開發體驗上有著顯著差異。

#### 1. Verilator 差異
**Windows 原生環境**:
- **可行性**: Verilator 不直接支持 Windows，必須借助 **Cygwin** 或 **MSYS2** 來模擬 Unix 環境。安裝和配置非常繁瑣，並且存在兼容性問題。
- **性能**: 在模擬環境中運行，I/O 性能較差，適合小規模測試，不適合大規模模擬。

**WSL**:
- **可行性**: 在 WSL2 中 Verilator 的可行性高，因為其基於 Linux 內核。安裝命令: (`sudo apt install verilator`)。
- **性能**: WSL2 性能接近原生 Linux，適合進行大量模擬和驗證，且兼容 Linux 工具鏈。

**Verilato**r 是一個高性能的開源工具，將 Verilog（一種硬體描述語言，用於設計數字電路）轉換為 C++ 或 SystemC 程式碼，從而可以在軟體環境中進行模擬和驗證。這種工具被稱為 硬體模擬器，用來 ==模擬和驗證數位電路的行為== ，特別是用於大型數位系統（如處理器、ASIC、FPGA）的設計與驗證。
應用: 數位電路設計驗證，系統模擬，FPGA/ASIC 前端驗證。

Verilator 和傳統的硬體模擬器（如 ModelSim 或 VCS）不同，它並不是解釋執行 Verilog 程序，而是將其轉換為等效的 C++/SystemC 程序，然後編譯並執行。因此，Verilator 的模擬速度通常比傳統的解釋器快很多。

#### 2. Chisel 開發環境差異
**Windows 原生環境**:
- **安裝與設置**: 必須手動安裝 Java JDK、Scala 和 sbt，並配置環境變量。工具安裝較為繁瑣。
- **兼容性問題**: 與某些 Unix 工具整合存在挑戰，尤其是 Verilator 和 GTKWave 的使用較為困難。

**WSL**:
- **安裝與設置**: 使用 Linux 包管理工具安裝更為簡單 (`apt` 安裝工具鏈)，且不需要繁瑣的環境變量設置。
- **兼容性**: WSL 中 Unix 工具鏈支持良好，能無縫整合 Verilator 和 GTKWave，模擬與驗證流暢。

#### 3. 文件系統與性能
**Windows 原生環境**:
- **文件系統**: NTFS 與 Unix 工具兼容性有限，可能影響到文件操作和腳本的運行。
- **性能**: 在文件 I/O 和 JVM 效率方面表現一般，特別是編譯 Scala 程式碼時，性能不及 Linux。

**WSL**:
- **文件系統**: 基於 Linux 的 ext4 文件系統，工具鏈運行穩定。能訪問 Windows 文件系統，開發更加靈活。
- **性能**: WSL2 的虛擬化技術使得性能接近 Linux 原生，適合大規模編譯和模擬工作。

#### 4. 工具與驗證
**Windows 原生環境**:
- **硬體驗證工具**: 需要依賴 Cygwin 或 MSYS2 模擬 Unix 環境來運行 Verilator，配置和性能表現均不理想。
- **波形查看器**: GTKWave 等工具需要額外安裝和配置，不如在 Linux 中運行那麼順暢。

**WSL**:
- **硬體驗證工具**: Verilator 和 GTKWave 等工具可直接通過 WSL 安裝，且與 Linux 環境中的工作流程一致，安裝簡單、性能良好。
- **波形查看器**: 可以通過 WSL 安裝 GTKWave，並在 Windows 中通過 XServer 顯示波形，體驗接近原生。

#### 5. 開發體驗
**Windows 原生環境**:
- **編輯器支持**: IntelliJ IDEA 和 VSCode 支持 Windows 開發，但命令行工具如 `make` 和 `grep` 的使用受限，整體體驗不如 Unix 系統靈活。
- **命令行操作**: PowerShell 和 cmd 的功能不及 bash 對 Unix 工具支持友好。

**WSL**:
- **命令行支持**: WSL 提供強大的 bash 終端，支援各種 Unix 工具，適合進行自動化腳本和命令行開發。
- **編輯器支持**: 可利用 VSCode 的 Remote - WSL 插件實現無縫開發，在 Windows 上編輯、在 WSL 中編譯運行，兼具兩者優勢。

:::
---

**Chisel 在 Anaconda (Windows) 和 VSCode (WSL) 上的差異比較**

| 特性 | Anaconda | VSCode |
|------------------------------|-------------------------------------------|---------------------------------------------|
| **環境設置** | 需要安裝 Scala 內核，設置相對簡單 | 需要安裝多個工具和依賴，設置較為繁瑣 |
| **編輯體驗** | 基本的程式碼編輯功能，無法重構、導航 | 完整的程式碼補全、重構、導航功能，編輯體驗強 |
| **程式碼執行** | 支持即時程式碼執行，適合逐步驗證 | 完整的編譯和執行流程，適合專業開發 |
| **性能** | 適合小型項目，性能一般 | 支持大型項目，性能優越 |
| **調試功能** | 支持基本的輸出檢查，無斷點調試 | 支持專業調試功能，適合處理複雜問題 |
| **模擬驗證** | 適合簡單模擬和測試 | 完整支持 Verilator 和波形查看工具 |
| **適用場景** | 教學、實驗、小型原型設計 | 專業項目開發、大規模設計 |

:::spoiler
#### 1. 環境設置與支持
**Jupyter Notebook**:
- **設置**: 使用 Chisel 需要在 Jupyter Notebook 上安裝一個 Scala 內核，如 **Almond**（Jupyter 支持 Scala 的內核）。設置過程相對簡單，通過 Conda 或其他包管理工具安裝 Almond 並配置 Jupyter 內核。
- **支持**: Jupyter Notebook 的主要用途是提供一個交互式的程式碼執行環境，適合編寫簡單的 Chisel 程式碼進行實驗和教學。它支持即時運行程式碼並查看輸出，對於小型電路設計和快速驗證非常方便。

**VSCode**:
- **設置**: 需要安裝 Scala 插件和 Chisel 的相關工具（如 Java JDK、Scala SDK、sbt）。VSCode 的設置相對繁瑣，需要手動配置多個工具，一旦配置好，支持完整的開發流程。
- **支持**: VSCode 更適合進行大規模的 Chisel 開發，支持完整的編譯、運行、測試流程，並且能與版本控制工具（如 Git）集成，適合專業開發。

#### 2. 編輯與開發體驗
**Jupyter Notebook**:
- **編輯體驗**: Jupyter 提供了一個基於筆記本的開發環境，允許逐步編寫和運行程式碼。它支持程式碼塊執行，對於調試和實驗設計非常友好。但它的編輯體驗相對較弱，沒有強大的程式碼補全、重構或導航功能。
- **交互性**: Jupyter 支持即時程式碼執行，適合開發者逐步驗證設計結果。每段程式碼可以獨立執行，並查看即時輸出結果，對於學習和探索新設計思路十分有用。

**VSCode**:
- **編輯體驗**: VSCode 提供了強大的程式碼補全、語法高亮、錯誤檢查和程式碼重構功能。它與 Scala 插件配合，提供了完善的 Chisel 開發支持。對於大規模工程開發、程式碼管理和結構化開發，VSCode 的編輯體驗更佳。
- **調試支持**: VSCode 支持完整的調試功能，可以設置斷點、查看變量和內存狀態，對於大型電路設計中更具挑戰性的問題排查非常有幫助。

#### 3. 程式碼執行與性能
**Jupyter Notebook**:
- **程式碼執行**: Jupyter Notebook 中，程式碼可以以單元塊的方式運行，這使得開發者能夠靈活地運行部分程式碼進行測試，而無需從頭編譯整個專案。這種方式非常適合用來測試 Chisel 的部分模組或功能。
- **性能**: 雖然可以進行即時執行和驗證，但由於 Jupyter 是基於交互式運行的，它不適合處理大型設計或進行複雜的模擬，整體性能比 IDE 弱一些。

**VSCode**:
- **程式碼執行**: VSCode 使用 sbt 作為構建工具，可以進行完整的編譯、測試和執行。它更適合編寫完整的硬體設計項目，並進行複雜的電路模擬和驗證。每次編譯時，VSCode 會編譯整個項目，這雖然不如 Jupyter 那樣即時，但更適合專案級別的開發。
- **性能**: 由於 VSCode 是專業的編輯器，它能夠更好地利用系統資源進行編譯和模擬，適合處理大型設計項目。其性能表現優於 Jupyter，特別是對於複雜設計和模擬的長時間運行。

#### 4. 調試與模擬
**Jupyter Notebook**:
- **調試能力**: Jupyter 的調試能力有限，主要依賴於手動打印輸出或執行單個程式碼單元來排查問題。它不支持傳統的調試工具如斷點設置，對於大型設計來說不太方便。
- **模擬驗證**: Jupyter 更適合進行簡單的設計驗證，無法進行大規模硬體設計的完整模擬。它可以用來進行一些 Chisel 程式碼的小型測試，但在整體設計驗證上表現有限。

**VSCode**:
- **調試能力**: VSCode 提供了專業的調試工具，可以設置斷點、逐步執行、檢查變量、查看執行流程，適合處理複雜的設計錯誤和進行詳細調試。
- **模擬驗證**: VSCode 支持完整的 Verilator 流程，可以進行詳細的硬體模擬和驗證，並且與 Verilog 生成、仿真和波形檢視等工具無縫集成，適合專業設計的驗證工作。

#### 5. 適用場景
**Jupyter Notebook**:
- **教學和原型設計**: Jupyter 非常適合 Chisel 的教學和學習，因為它可以逐步運行程式碼並實時查看結果。對於快速驗證想法、進行小型設計原型非常方便。
- **實驗與演示**: 由於其交互式特性，Jupyter 非常適合進行實驗和演示，能夠快速展示 Chisel 程式碼如何轉換成硬體行為。

**VSCode**:
- **專業開發**: 對於專案級別的硬體設計，VSCode 更為合適。它提供了專業的編輯、編譯、測試和調試工具，適合進行從設計到驗證的完整流程。
- **大規模設計**: 如果你正在進行一個大規模的硬體設計項目，VSCode 能提供完善的項目管理、版本控制和測試支持，是進行專業 Chisel 開發的理想選擇。

### 總結
- **Jupyter Notebook** 非常適合 Chisel 的初學者或教學用途，因為它的交互式環境能幫助快速驗證和實驗，但在處理複雜的硬體設計和模擬時顯得力不從心。
- **VSCode** 則是一個更適合專業 Chisel 開發的環境，提供了強大的編輯、調試和模擬工具，非常適合大規模設計。
:::
---
### Chisel 安裝參考資料整理(重要!!)

#### 1. 官方安裝流程（建議查閱）
提供完整的 Chisel 安裝流程和詳細的官方文件，建議優先參考官方文件以確保最新及正確的安裝方式。
- [Chisel 官方安裝流程](https://www.chisel-lang.org/docs/installation)

#### 2. Chisel GitHub 專案頁面
包含 Chisel 的安裝指南和更多細節，可供了解相關工具和範例。
- [Chisel GitHub 專案安裝指南](https://github.com/chipsalliance/chisel#installation)

#### 3. 在 Windows 系統上安裝 WSL
若使用 Windows 系統，可參考微軟官方文檔安裝 Windows Subsystem for Linux（WSL）以便在 Windows 上執行 Linux 環境，再進行 Chisel 安裝。
- [微軟官方 WSL 安裝文檔](https://learn.microsoft.com/zh-cn/windows/wsl/install)

#### 4. 安裝 Chisel 詳細步驟與個人經驗分享
提供 Chisel 安裝過程中的詳細操作說明和個人經驗，可作為安裝時的參考。
- [CSDN：Chisel 安裝指南與詳細步驟](https://blog.csdn.net/weixin_43681766/article/details/124910441)
- [CSDN：Chisel 在 WSL 上安裝經驗分享](https://blog.csdn.net/qq_46170379/article/details/121450806)