# 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/dv，シミュレーションのベクタなどの追加・修正を行います．
- verilog/includes_folder，シミュレーション対象のRTLファイルを設定します．
```{note}
RTLファイルの指定はビルドとシミュレーションで独立しており，シミュレーション結果と作製するチップ間で異なるRTLの組み合わせでない事に注意が必要です．
```
### RTL ファイルの追加と修正
verilog/rtl のユーザ領域コードの修正や S-box テーブルの Verilog HDL ファイルを追加します．
ファイルの追加： AES_SBOX_ENC.v を追加します．
AES_SBOX_ENC.v
```{literalinclude} ./files/AES_SBOX_ENC.v
```
### 環境変数設定
## Caravel template のダウンロード
環境変数の設定を行い，Caravel template のディレクトリに移動します．
```
source setenv.sh
cd caravel_mpw-9k
```
Caravel template (mpw-9k) ディレクトリを作成し，efabless 社の git サイトから Caravel template (caravel_user_template) レポジトリの mpw-9k タグのテンプレートをクローンします．
```
mkdir Caravel_mpw-9k
cd Caravel_mpw-9k
git clone -b mpw-9k https://github.com/efabless/caravel_user_project.git caravel_mpw-9k
```
### 環境変数の設定ファイルの作成
まず，ツールなどの導入や利用に必要な環境変数の設定を行うファイルをあらかじめ作成します．ファイル名を setenv.sh とします．
```
export OPENLANE_ROOT=$HOME/Caravel_mpw-9k/dependencies/openlane_src
export PDK_ROOT=$HOME/Caravel_mpw-9k/dependencies/pdks
export PDK=sky130A
export CARAVEL_ROOTT=$HOME/Caravel_mpw-9k/caravel_mpw-9k/caravel
```
コマンドラインからファイルを生成する方法
```
touch setenv.sh
echo "export OPENLANE_ROOT=\$HOME/Caravel_mpw-9k/dependencies/openlane_src" | tee -a setenv.sh
echo "export PDK_ROOT=\$HOME/Caravel_mpw-9k/dependencies/pdks" | tee -a setenv.sh
echo "export PDK=sky130A" | tee -a setenv.sh
echo "export CARAVEL_ROOTT=\$HOME/Caravel_mpw-9k/caravel_mpw-9k/caravel" | tee -a setenv.sh
```
### ツール・PDK のセットアップ
環境変数の設定を行い，Caravel template ディレクトリに移動します．
```
source setenv.sh
cd caravel_mpw-9k
```
セットアップ前に Makefile を編集します．
回路合成結果をチェックする precheck のインストールフォルダを下記の通り修正します．
```diff
- PRECHECK_ROOT?=${HOME}/mpw_precheck
+ PRECHECK_ROOT?=${HOME}/Caravel_mpw-9k/precheck_mpw-9k
```
Caravel template の環境を Rootless mode の Docker により利用するための修正を行います．
```diff
- ROOTLESS ?= 0
+ ROOTLESS ?= 1
```
上記の ROOTLESS 設定で Rootless mode に切り替わらないため，261, 273, 289 行あたりの「-u」オプション行を削除します．
```diff
- -u $(shell id -u $(USER)):$(shell id -g $(USER)) \
```
Makefile ファイルの修正後，セットアップ実行します．１０分程度要します．
```
make setup
```
## テンプレートを利用した最小構成の回路の合成
テンプレートの初期サンプル回路を合成し，Caravel template 環境を用いたビルドの手順を確認します．なお，回路合成にはおよそ１～２時間程度を要します．
サンプル回路は 16-bit のカウンタ回路であり，カウンタの値がユーザ用 IO に接続されています．また，Caravel 制御回路の RISC-V プロセッサと Wishbone バス，内部ロジックアナライザにも接続されており，Caravel 制御回路からユーザ回路を操作する機構を試用することもできます．
クロックやリセットも Caravel 制御回路により生成されます．
### サンプル回路の修正
サンプル回路の IO (GPIO) の電源投入時の設定を記述するファイル verilog/rtl/user_define.v の修正を行う必要があります．
verilog/rtl/user_define.v 中の USER_CONFIG_GPIO_*_INIT が GPIO_MODE_INVALID と無効に設定されており，これを GPIO_MODE_USER_STD_OUTPUT に修正します．（下記の例）
```
`define USER_CONFIG_GPIO_5_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_6_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_7_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_8_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_9_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_10_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_11_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_12_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_13_INIT `GPIO_MODE_USER_STD_OUTPUT
// Configurations of GPIO 14 to 24 are used on caravel but not caravan.
`define USER_CONFIG_GPIO_14_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_15_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_16_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_17_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_18_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_19_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_20_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_21_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_22_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_23_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_24_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_25_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_26_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_27_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_28_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_29_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_30_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_31_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_32_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_33_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_34_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_35_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_36_INIT `GPIO_MODE_USER_STD_OUTPUT
`define USER_CONFIG_GPIO_37_INIT `GPIO_MODE_USER_STD_OUTPUT
```
### 回路合成の実行
user_define.v の修正後，ユーザ回路本体（user_proj_example）と Caravel と接続するラッパー（user_project_wrapper）の合成を実行します．
```
make user_proj_example
make user_project_wrapper
```
エラーなど表示されず回路合成が成功すると「Flow complete」と表示され，gdsフォルダ下に user_progect_wrapper.gds ファイルが生成されます．
## チップ作製データのチェック
回路合成により得られるチップ作製データの整合性などのチェックを行います．
チェックではチップ製造の工程との整合性チェックのほか，説明ファイル README.md の内容についてもチェックされます．
### チェック用スクリプトの修正
Caravel_mpw-9k/precheck_mpw-9k/docker-mount.sh ファイル 19 行あたりの「-u」オプション行を削除します．（Docker の Rootless mode に対応する修正です）
```diff
- -u $(id -u "$USER"):$(id -g "$USER") \
```
### README の修正
README.md を下記の例のように書き換えます．
```
This project is minimally modified to mpw-9i caravel template.
The function is 32-bit counter. 16-bit IOs are set to OUTPUT.
```
なお，README.md に原文が残っている場合や README.bak などオリジナルの複製など残している場合もチェックにてエラーが報告されます．
### チェックの実行
下記コマンドによりチェックを実行します．
チェック中に不具合が見つかった場合でも全ての項目が確認され，１時間程度要します．
```
make run-precheck
```
全て項目のチェックに合格すると All Checks Passed !!! と表示されます．