IIC-OSICによるオープンソース設計環境のセットアップ
0．更新履歴
2023/10/06 ISHI会版 Docker について追記，IIC-OSIC TOOLSの名称変更に対応
1．IIC-OSIC について
1.1 IICの紹介
この記事では Institute for Integrated Circuits (IIC), Jophannes Kepler University Linz (JKU) がメンテナンスしているツールセットを用いてオープンソースIC設計環境をセットアップする手順を説明します．github にいろいろ公開されていますが，IIC-OSIC が設計環境のセットアップに使うリポジトリです．後述しますが2種類あります．
オープンソースEDAは急速に発展を続けているため設計環境は油断するとすぐに陳腐化してしまうのですが，Prof. Harald Pretl をはじめとする IICのグループは SSCS PICO Program にも深く関わっておりアップデートは迅速でオープンソースシリコンの Slack ワークスペース https://open-source-silicon.dev/ でもすぐにレスポンスがあります．信頼して使いましょう．
1.2 2つのIIC-OSIC
IIC の用意する設計環境には2種類あります．Docker container になっているものと，Linux 環境にインストールしていくものです．名前がややこしいのですが前者が IIC-OSIC-TOOLS (リポジトリ名 iic-osic-tools)，後者が IIC-OSIC TOOLS (リポジトリ名 iic-osic) です． 名前がややこしかったためか，非Docker版の名称が OSIC Multitool に変更されました．Docker版は IIC-OSIC-TOOLS のままです．
こっちは Docker になっている方で
こっちは Linux (Ubuntu) にインストールしていく方．
間違えないようにしましょう．
どちらを選んでも設計はできます．おおざっぱに両者の特徴を書くと，
IIC-OSIC-TOOLS (Docker container)
メリット
Docker の上で動くので，環境に依存せず確実に動く
意図しない操作で環境を壊すことがない
デメリット
ツールやPDKのインストールは難しい
Docker の上で動かすので非力なマシン上だと重い
OSIC Multitool (旧IIC-OSIC TOOLS)
メリット
Docker を介さないので軽い
ツールやPDKのインストールができる
デメリット
場合によっては追加のパッケージのインストールなどが必要
操作によっては環境が壊れる可能性がある
といったところで，Linux 環境を使ったり管理したりすることに慣れていない場合は IIC-OSIC-TOOLS を使うのがいいと思います．いろいろカスタマイズしたいとか，ツールやPDKは最新じゃないと嫌だという人は IIC-OSIC TOOLS OSIC Multitool をインストールしましょう．
2．筆者環境
筆者はどちらの環境も Windows 11 上で動かしているので，以下の解説は Windows 11上での話です．ちょっと前まで Windows 10 でやっていたので，Windows 10 でも一緒だと思います．Windows 10 の頃に書いた記事はこちら．
IIC-OSIC-TOOLS は Docker container なので，Docker さえ動けばホストOSが何であっても動くはずですが試していません．
3．IIC-OSIC-TOOLS (Docker container) のインストール
ここでは IIC-OSIC-TOOLS (Docker container になっている方) をインストールする手順を解説します．
3.1 必要なツールをインストールする
・Docker Desktop
Docker container なので当然ながら Docker が要ります．Docker Desktop をインストールしましょう．
WSL2の更新が必要だったり，そもそもBIOSで仮想化が… とかいろいろあるかも知れませんがそこはがんばって解決してください．調べたら情報がでてきます．Docker Desktop を起動して，以下のような画面になればOKです．左下のDockerアイコンのところが緑色でなく橙色になっている場合は何らかの原因で起動がうまくいっていません．原因を調べて解決しましょう．
・git (必要なら)
IIC-OSIC-TOOLS は github のリポジトリ上にあるので，取ってくるのに git が必要です．また，OpenMPW でテープアウトしようとするのであれば git は必要ですし，公開されているプロジェクトのデータをもらうにも git を使うのが便利です．ここでは git for windows を使うことにします．WSL上に Linux 環境あるからそっちの git 使う，という人はスキップして構いません．git for windows のサイトはこちら．
インストール中，設定項目がたくさんありますが，とりあえずデフォルトでいいでしょう．
・X Server (必要なら)
オープンソースEDAツールの GUI は X Window System を使っているので，画面の描画に X Server が必要です．Windows なら VcXsrv を使いましょう．Mac では XQuartz がいいらしいですが，使ったことありません (そもそも Mac 使ったことないので…)．VNC を使ってブラウザから操作するという方法もあるので． VNC を使うなら X Server なしでも使うことはできます．
3.2 IIC-OSIC-TOOLS のインストール
git bash を起動します．(単に私がコマンドラインの方がやりやすいというだけなので，git GUI でも構いません．) こんな画面が開きます．
clone したリポジトリを置くフォルダに移動します．デフォルトだと C:\Users\username\ にいるので，Documents に移動してから clone することにします．iic-osic-tools の githubページで，Code から URL をコピーして，git clone します．
下のような感じで clone が終わります．終わったら git bash は閉じて構いません．
clone したら，PowerShell を開いて clone したフォルダに移動します．ここでは C:\Users\tsuchiya\Documents\iic-osic-tools です．フォルダ内に以下のようなファイルがあることを確認してください．
"start_vnc.bat" がインストールスクリプトを兼ねていますので，start_vnc.bat を実行します (.\start_vnc.bat) ．このスクリプトは不足しているファイルをダウンロードしますので，ネットワークの状況にもよりますが10分以上かかります．ダウンロード中の画面はこんな感じ．
無事に終わったら以下のように "Status: Downloaded newer image for …" と表示されます．
3.3 動作確認 (VNC)
IIC-OSIC-TOOLS には起動方法が2つあり，VNCサーバにブラウザからアクセスする方法と，X Server を使用する方法があります．インストールに使った start_vnc.bat は VNCモードでの起動スクリプトでもあるので，インストールが終わったらすでに VNCモードで IIC-OSIC-TOOLS が起動しているはずです．Docker Desktop を開いて確認しましょう．下の画面のように，STATUS が Running になっていれば OK です．
この状態でブラウザから http://localhost にアクセスし，パスワード abc123 を入力すると以下のようにデスクトップ画面がブラウザ上に開きます．
例えばターミナルを起動し，xschem を起動してみると下のように使うことができます．
止めたい場合は Docker Desktop から Stop します．また，再開するときはいちいち PowerShell を起動しなくても Docker Desktop から起動することができます．
3.4 動作確認 (X Server)
IIC-OSIC-TOOLS のもう一つの起動方法は X Server を使用する方法です．X Server を使うと，IIC-OSIC-TOOLS のウィンドウを独立したウィンドウとして使うことができます．初回のみ，PowerShell から start_x.bat を実行します．
「初回のみ」と書いたのは，上の画像の4行目 "Container does not exist, creating iic-osic-tools_xserver …" のためです．これによって Xサーバ用のコンテナが登録され，Docker Desktop から操作ができます．
iic-osic-tools_xserver がContainers に登録されています．X Server を起動してから，iic-osic-tools_xserver を Start すると下のようなウィンドウが開きます．
試しに xschem とコマンドを入力して Xschem を起動すると，Xschem が独立したウィンドウとして開くはずです．
なお，ターミナルを終了すると自動的にコンテナ (iic-osic-tools_xserver) は Stop します．
3.5 Caravel の設計フロー
OpenMPW でテープアウトするための caravel の設計フローは他の記事で解説していますが，Docker版 IIC-OSIC-TOOLS ではこの通りやっても動きません．
なぜなら設計環境自体が Docker上で動いているため，OpenLane を Docker 上で動かそうとする caravel ではエラーになります．試しに caravel_user_project を clone して make setup しようとすると，以下のようになります．
% export OPENLANE_ROOT=$PWD/dependencies/openlane_src
% export PDK_ROOT=$PWD/dependencies/pdks
% export PDK=sky130B
% make setup
(snip)
make[2]: Entering directory '/foss/designs/caravel_user_project/dependencies/openlane_src'
Makefile:23: warning: undefined variable 'DOCKER_SWAP'
Makefile:26: warning: undefined variable 'DOCKER_MEMORY'
Makefile:42: warning: undefined variable 'ROUTING_CORES'
/bin/sh: 1: docker: Permission denied
make[2]: *** [Makefile:99: pull-openlane] Error 127
make[2]: Leaving directory '/foss/designs/caravel_user_project/dependencies/openlane_src'
make[1]: *** [Makefile:84: openlane] Error 2
make[1]: Leaving directory '/foss/designs/caravel_user_project/openlane'
make: *** [Makefile:180: openlane] Error 2
docker から docker を起動しようとしているため，docker を起動しようとしたところで止まっています．まぁ docker から docker を動かす手がないわけではなく dind (docker-in-docker) とか dood (docker-outside-of-docker) とかありますが…
ちなみに，環境変数を設定せずに IIC-OSIC-TOOLS上の OpenLane (/foss/tools/openlane) を使おうとしてもエラーになります．IIC-OSIC-TOOLS では基本的に /foss/designs 以外は触れないようになっているためです．
% make setup
(大量の Permission denied エラー)
rm: cannot remove '/foss/tools/openlane/2022.12/.readthedocs.yml': Permission denied
rm: cannot remove '/foss/tools/openlane/2022.12/requirements_lint.txt': Permission denied
rm: cannot remove '/foss/tools/openlane/2022.12/run_designs.py': Permission denied
make[1]: *** [Makefile:83: openlane] Error 1
make[1]: Leaving directory '/foss/designs/caravel_user_project/openlane'
make: *** [Makefile:180: openlane] Error 2
IIC-OSIC-TOOLS にはすでに OpenLane がインストールされているので，caravel の Makefile を使わずに flow.tcl を直接実行する，というのが正しい方法です．caravel_user_project の標準フローを以下のように変更します．
% git clone https://github.com/efabless/caravel_user_project.git -b mpw-9a
% cd caravel_user_project
%mkdir dependencies
%export OPENLANE_ROOT=$PWD/dependencies/openlane_src
%export PDK_ROOT=$PWD/dependencies/pdks
% export PDK=sky130B
%make setup
%make user_proj_example% cd openlane
% flow.tcl -design user_proj_example -tag foo -overwrite
dependencies ディレクトリは OpenLane と PDK のインストール用なので不要
環境変数はデフォルトで設定されている (OPENLANE_ROOT=/foss/tools/openlane，PDK_ROOT=/foss/pdks) ものから変更してはダメ
環境変数 PDK は使う PDK に合わせて適宜変更 (IIC-OSIC-TOOLS のデフォルトは sky130A)
make setup は OpenLane と PDK のインストール用なので実行不要
make <project_name> は docker を呼ぼうとするので使わずに，openlane ディレクトリに下りて flow.tcl を直接実行
これで /foss/tools/openlane にインストールされた OpenLane が走って合成ができます．
4．OSIC Multitools (旧IIC-OSIC TOOLS)のインストール
Docker container ではなく，Linux環境にツール群をインストールします．Windows 11上の WSL (もちろん WSL2) 上の Ubuntu 22LTS にインストールしていきます．
OSIC Multitool に変わってからテストしていないため，以下 iic-osic の頃の記述のままです．基本的に名前の読みかえ (iic-osic → oss-multitool) で行けると思います．
4.1 IIC-OSIC のインストール
リポジトリ iic-osic を clone します．
iic-osic のファイル構成は以下のようになっているはずです．
iic-osic-setup.sh がインストールスクリプトです．
(2022/12/10現在) インストールスクリプトで指定している Ngspice のバージョン (36) が古いため，このまま実行するとエラーになります．iic-osic-setup.sh の以下の場所を現行の 38 に書き換えます．
export NGSPICE_VERSION=36
export NGSPICE_VERSION=38
書き換えができたら実行します．システムへのインストールなので root権限が必要で，sudo のパスワードが必要です．
ここからインストールが始まりますが，大量のパッケージ (筆者のときで700個) がインストールされた上に OpenLane等のツール群とPDKのインストールが走るので，相応に時間がかかります．無事に終了すると以下のようになります．
ホームディレクトリにいくつかのディレクトリ・ファイルができています．インストール後は iic-osic は消しても構いませんが，後述するようにアップデートに使うので残しておいた方がいいでしょう (まぁ github から最新版を clone してもいいですが)．他のものは消すと動かなくなるので消してはいけません．
iic-init.sh がPDKを設定しているスクリプトです．source しましょう．面倒だったらログイン時に source するようにしてもよいでしょう．ただし，デフォルトでは PDK が sky130A になっています．他の PDK を使うときはスクリプトを修正してください．試しに xschem を起動すると以下のように Xschem が立ち上がります．
Windows 11 で WSL を使う場合，X Server を立ち上げなくても GUI が使えます．Windows 11 は WSL に X Serverを統合した WSLg に対応しており，VcXsrv などが不要になりました．地味に便利．
2022年12月現在，Klayout は Ruby とのバージョン整合性問題でエラーが出るため手動で最新版を入れる必要があります．詳細は「5.1 Klayout のバージョン問題」を見てください．
念のため OpenLane の方も確認しておきましょう．~/OpenLane に移動して，make test を実行します．正常にインストールできていればパスするはず．
4.2 Caravel の設計フロー
Docker版と違い，こちらは docker を起動できますので caravel 標準のフローを実行することができます．
4.3 環境のアップデート
IIC-OSIC は活発にアップデートが続けられているので，新しく設計を始めるときは最新の環境にアップデートしましょう．インストールスクリプト iic-osic/iic-osic-setup.sh を実行すると環境がアップデートされます．
5．トラブルシューティング
トラブったときの解決メモ．
5.1 Klayout のバージョン問題
Klayout は Ruby とのバージョン整合性問題があります．2022年12月現在，手動でのアップデートが必要です．
5.1.1 (2022/12/10現在) Klayout のアップデート (0.27)
2022/12/10現在，IIC-OSIC でインストールされる Klayout は 0.26 ですが，このバージョンで使われている ruby のスクリプトは Ruby 3系と互換性のない箇所があり，以下のようにエラーが出ます．
詳しくはこちら．
というわけで，最新版に上げましょう．この記事を書いているまさに今日 (2022/12/10)，0.28 がリリースされました．
… ところが 0.28 は WSLのバグを踏んでおりインストールしようとするとエラーが出ます (詳しくは次節)．というわけで 0.27 をインストールします．GetKLayout → Ubuntu 22 から 0.27 をダウンロードし，dpkg --install klayout_0.27.13-1_amd64.deb でインストールします．libqt5opengl5 が必要なので，あらかじめ apt install でインストールしておきましょう．これで klayout を起動すると 0.27 が起動します．ruby 3.0 との非互換によるエラーも出ません．
5.1.2 (2022/12/10現在) Klayout のアップデート (0.28)
KLayout 0.28 をインストールしようとすると，以下のようなエラーになります．
そもそも WSLのバグというのはこれのことです．
shared library がシンボリックリンクになってない．報告されたのはけっこう前なのですが，なぜか残っています．解決方法は上の github のスレッドにあるんですが，何故か 0.27 をインストールした後だと 0.28 がすんなりインストールできます．
別にシンボリックリンクの問題が解決されたわけではないんですが．
あまりきちんと検証していないのですが，0.27 → 0.28 とインストールすることで 0.28 にすることができました．
なんだか釈然としませんが，まあいいか．きっと IIC-OSIC のアップデートで手動インストールしなくてもよくなるでしょうし．
5.2 OpenLane の Permission Denied
Linux (Ubuntu) 環境下で発生．caravel_user_project でサンプルを合成しようとすると OpenLane が Permission denied で止まる．
[INFO]: Using configuration in '../home/tsuchiya/caravel_user_project/openlane/user_proj_example/config.tcl'...
[ERROR]: Traceback (most recent call last):
File "/openlane/scripts/config/tcl.py", line 490, in <module> cli()
File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1128, in __call__ return self.main(*args, **kwargs)
File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1053, in main rv = self.invoke(ctx)
File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1659, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1395, in invoke return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python3.6/site-packages/click/core.py", line 754, in invoke return __callback(*args, **kwargs)
File "/openlane/scripts/config/tcl.py", line 411, in extract_process_info with open(output, "w") as f:
PermissionError: [Errno 13] Permission denied: '/home/tsuchiya/caravel_user_project/openlane/user_proj_example/runs/22_12_04_22_13/config_in.tcl'
これはどうも docker が volume mount するときのパーミッションのせいらしい．詳しくは github の issue
この issue にあるように，openlane/Makefile で -u オプションを外せば動くようになる．具体的にはこの部分の -u の行をコメントアウト
docker_run = \ docker run $(docker_startup_mode) \ $(docker_mounts) \
$(docker_env) \
-u $(shell id -u $(USER)):$(shell id -g $(USER))
docker はよく分からん．
6．ISHI会版 Docker
日本国内でオープンソースICの情報交換を行なうコミュニティ ISHI会では
IIC-OSIC-TOOLS を基に設計環境を整備しています．
この記事が気に入ったらサポートをしてみませんか？