# Caravel template へのユーザ回路追加
本ドキュメントでは，サンプル回路の16-bitカウンタに AES の 8-bit S-Box のテーブルを追加し，ユーザ回路の追加からチップ作製データの作成やシミュレーションを行います．
```{note}
なお，本ドキュメントでは，efabless 社 chipignite シャトルサービスを利用しました際のチップ作製データの生成手順を記述しています．チップ作製の詳細については，efabless 社へお問い合わせ下さい．
```
## Caravel template 環境のディレクトリ構成
Caravel template 環境は下記のディレクトリ上に構築されているとします．
以下の項では，setenv.sh により環境設定がなされており，また，操作などは全て Caravel_mpw-9k/caravel_mpw-9k ディレクトリ上で実行することを想定しています．
```
$HOME/
|-- Caravel_mpw-9k/
|-- caravel_mpw-9k/
|-- dependencies/
| |-- openlane_src/
| |-- pdks/
|-- precheck_mpw-9k/
|setenv.sh
```
## ユーザ回路のソースコードの修正・追加
Caravel template (Caravel_mpw-9k/caravel_mpw-9k) へユーザー回路を追加する際は，次のディレクトリへの操作を行います．
- verilog/rtl，ユーザ回路のRTLファイルの追加・修正を行います．
- openlane，ビルド対象のRTLファイルなどの設定を行います．
- verilog/rtl/user_defines.v ファイルは環境構築時に修正されているとしています．
また，論理シミュレーションでは，別途，次のディレクトリへの操作を行います．
- verilog/dv，シミュレーションのベクタなどの追加・修正を行います．
- verilog/includes_folder，シミュレーション対象のRTLファイルを設定します．
```{note}
RTLファイルの指定はビルドとシミュレーションで独立しており，シミュレーション結果と作製するチップ間で異なるRTLの組み合わせでない事に注意が必要です．
```
### RTL ファイルの追加と修正
verilog/rtl のユーザ領域コードの修正や S-box テーブルの Verilog HDL ファイルを追加します．
ファイルの追加： AES_SBOX_ENC.v を verilog/rtl ディレクトリへ追加します．
AES_SBOX_ENC.v
```{literalinclude} ./files/AES_SBOX_ENC.v
```
ユーザ領域コードの修正： verilog/rtl/
パッチファイルを利用して，ユーザ領域の回路本体 user_proj_example.v，制御回路との接続記述 user_project_wrapper.v を修正します．
user_proj_example.v では標準で 16-bit カウンタが実装されています．このカウンタの下位 8-bit を S-box モジュールへ入力し，8-bit の出力を得たのち，入出力の計 16-bit を出力するように修正します．また，Wishbone バスや内部ロジックアナライザの接続も同様に変更します．
```$HOME/Caravel_mpw-9k``` ディレクトリに下記の内容の user_proj_example.v.patch を作成し，適用します．
user_proj_example.v.patch
```{literalinclude} ./files/user_proj_example.v.patch
```
```
patch --dry-run caravel_mpw-9k/verilog/rtl/user_proj_example.v < user_proj_example.v.patch
patch caravel_mpw-9k/verilog/rtl/user_proj_example.v < user_proj_example.v.patch
```
user_project_wrapper.v では，ユーザ IO の出力を [37:30] [7:0] から [23:8] へ変更します．これは，ユーザ IO の先頭 8-bit が Caravel 制御回路の GPIO や SPI ROM，UART にも割り当てられており，チップの動作テストではこれら機能を利用するためです．
```$HOME/Caravel_mpw-9k``` ディレクトリに下記の内容の user_project_wrapper.v.patch を作成し，適用します．
user_project_wrapper.v.patch
```{literalinclude} ./files/user_project_wrapper.v.patch
```
```
patch --dry-run caravel_mpw-9k/verilog/rtl/user_project_wrapper.v < user_project_wrapper.v.patch
patch caravel_mpw-9k/verilog/rtl/user_project_wrapper.v < user_project_wrapper.v.patch
```
### ビルド設定ファイルの修正
user_proj_example のビルド時に AES_SBOX_ENC.v を含める設定を openlane/user_proj_example/config.json へ追加します．
verilog/rtl のユーザ領域コードの修正や S-box テーブルの Verilog HDL ファイルを追加します．
```$HOME/Caravel_mpw-9k``` ディレクトリに下記の内容の config.json.patch を作成し，適用します．
config.json.patch
```{literalinclude} ./files/config.json.patch
```
```
patch --dry-run caravel_mpw-9k/openlane/user_proj_example/config.json < config.json.patch
patch caravel_mpw-9k/openlane/user_proj_example/config.json < config.json.patch
```
### シミュレーション設定ファイルの修正
RTL シミュレーション実行時に AES_SBOX_ENC.v を含める設定を verilog/includes/includes.rtl.caravel_user_project へ追加します．
このほか，IO ポートのシミュレーション用ベクタ verilog/dv/io_ports/io_ports_tb.v のピン配置修正を行い，Caravel 制御 VexRiscv プロセッサの起動ファームウェアのコード verilog/dv/io_ports/io_ports.c を修正します．
```$HOME/Caravel_mpw-9k``` ディレクトリに下記の内容の３つのファイルを作成します．
includes.rtl.caravel_user_project.patch
```{literalinclude} ./files/includes.rtl.caravel_user_project.patch
```
io_ports_tb.v.patch
```{literalinclude} ./files/io_ports_tb.v.patch
```
io_ports.c.patch
```{literalinclude} ./files/io_ports.c.patch
```
パッチのチェックを行います．
```
patch --dry-run caravel_mpw-9k/verilog/includes/includes.rtl.caravel_user_project < includes.rtl.caravel_user_project.patch
patch --dry-run caravel_mpw-9k/verilog/dv/io_ports/io_ports_tb.v < io_ports_tb.v.patch
patch --dry-run caravel_mpw-9k/verilog/dv/io_ports/io_ports.c < io_ports.c.patch
```
パッチを適用します．
```
patch caravel_mpw-9k/verilog/includes/includes.rtl.caravel_user_project < includes.rtl.caravel_user_project.patch
patch caravel_mpw-9k/verilog/dv/io_ports/io_ports_tb.v < io_ports_tb.v.patch
patch caravel_mpw-9k/verilog/dv/io_ports/io_ports.c < io_ports.c.patch
```
## 回路合成の実行
ユーザ回路の追加・修正やビルド・シミュレーション設定の修正後，ユーザ回路本体（user_proj_example）と Caravel へ接続するラッパー（user_project_wrapper）の合成を実行します．
```
make user_proj_example
make user_project_wrapper
```
エラーなど表示されず回路合成が成功すると「Flow complete」と表示され，gdsフォルダ下に user_progect_wrapper.gds ファイルが生成されます．
## チップ作製データのチェック
回路合成により得られるチップ作製データの整合性などのチェックを行います．
チェックではチップ製造の工程との整合性チェックのほか，説明ファイル README.md の内容についてもチェックされます．
### README の修正
README.md を下記の例のように書き換えます．
```
This project is minimally modified to mpw-9k caravel template.
The function are a 16-bit counter and an S-box table. 16-bit IOs are set to OUTPUT.
```
### チェックの実行
下記コマンドによりチェックを実行します．
チェック中に不具合が見つかった場合でも全ての項目が確認され，１時間程度要します．
```
make run-precheck
```
全て項目のチェックに合格すると All Checks Passed !!! と表示されます．