Altera® SoC FPGA をターゲットとした Linux デバイスツリーの作成・編集作業に適用可能な３つの方法について紹介します。
はじめに
SoC FPGA エンベデッド開発スイート（SoC EDS）には、Linux デバイスツリーを生成するための専用ツール（デバイスツリー・ジェネレーター（sopc2dts））が付属していますが、SoC EDS 付属の Linux リファレンス環境（GSRD）向けに用意された限定的なツールとなっており万能ではありません。sopc2dts 利用の条件に適合しない場合には、付属のツールを使用せず一般的な方法で対応する必要があります。
メーカー発行のドキュメントにも以下のように注意書きがあります。
❝Warning: The Linux Device Tree Generator is tested with and supports only the Linux
kernel version targeted by the associated GSRD. It is not recommended to use the
Linux Device Tree Generator if your design targets a different Linux kernel version.
Instead, it is recommended to manage the Device Tree manually by using the Device
Tree files provided by the kernel as a baseline, and by adding the FPGA IP and board
information manually.❞ ［SoC FPGA Embedded Development Suite User Guide より引用］
Linux 開発で使用する一般的な方法を含め、適用可能な方法として下記の３通りがあります。
- 方法1: sopc2dts ツールを使用して作成する
- 方法2: Linux ソースツリーを使用して make コマンドで作成する
- 方法3: dtc を使用して作成および編集する
以下、それぞれの方法について手順と補足情報を記載します。
方法1: sopc2dts ツールを使用して作成する
最初に SoC EDS に付属するデバイスツリー・ジェネレーター（sopc2dts）を使用する方法について記載します。冒頭に記載した通りこの方法は万能ではありません。以下の要件をご理解頂いたうえでご使用ください。
- SoC EDS に付属の Linux リファレンス環境（GSRD）に適用される Linux カーネルバージョンのみが対象（その他のバージョン向けは動作未確認。全ての Linux バージョンに対応する物ではない）。
- Cyclone® V / Arria® V / Arria® 10 のみが対象（Stratix® 10、Agilex™ は対象外）。
この方法のメリットとして FPGA 側の IP コンポーネント向けのデバイス定義が生成可能となっていることがありますが、全ての IP コンポーネントの定義が生成できる訳ではないという点にも注意が必要です。
デバイスツリーの生成に対応していない IP コンポーネントでは、
「compatible = "unknown,unknown-1.0";」を含むデバイス定義が生成されます。unknown となったデバイス向けのドライバーがデバイスツリーを必要とする場合、手作業でデバイスツリー・ソースを記述して対応する必要があります。
参考：
sopc2dts の使い方は Rocketboards.org の下記ページも併せてご参照ください。
Generating the Device Tree（for Cyclone® V / Arria® V）
Generating the Linux Device Tree（for Arria® 10）
1-1: 入力ファイルの準備
入力ファイルは、Platform Designer から生成される .sopcinfo ファイルと、ボードの情報を含む .xml ファイルの 2 種類です。必要となる入力ファイル一式を作業用のディレクトリー内に用意します。
.sopcinfo はターゲットとなる Quartus プロジェクト以下に生成されたファイルを使用します。
.xml ファイルは Quartus ツールからは生成されません。Development Kit 向けに SoC EDS に付属しているハードウェア・リファレンス（GHRD）に含まれる .xml ファイルをコピーしてご使用ください。デバイスファミリーに応じて、以下の場所から該当の .xml をコピーしてください。
C:\intelFPGA\18.1\embedded\examples\hardware\cv_soc_devkit_ghrd
C:\intelFPGA\18.1\embedded\examples\hardware\av_soc_devkit_ghrd
C:\intelFPGA\18.1\embedded\examples\hardware\a10_soc_devkit_ghrd
該当の .xml ファイルは次の通りです。
| デバイスファミリー | ボード情報（Board XML） |
| Cycone® V SoC | soc_system_board_info.xml hps_common_board_info.xml |
| Arria® V SoC | ghrd_5astfd5k3_board_info.xml hps_common_board_info.xml |
| Arria® 10 SoC | hps_a10_common_board_info.xml hps_a10_devkit_board_info.xml ghrd_10as066n2_board_info.xml |
1-2: sopc2dts 実行方法
作業は Embedded Command Shell 上で行います。Shell 起動後、入力ファイル一式を用意した作業用ディレクトリーに移動し、sopc2dts コマンドを実行するのみです（Windows でも使用可能です）。
Shell の起動は、Linux ホスト環境では下の例のように embedded_command_shell.sh を実行。Windows ホスト環境ではスタートメニューから SoC EDS Command Shell をクリックします。
$ ~/intelFPGA/18.1/embedded/embedded_command_shell.sh
1-3: sopc2dts 実行例
デバイスツリー・ソース（.dts）、デバイスツリー・ブロブ（.dtb）それぞれを生成するためのコマンドライン例を記載します。--input オプションに指定する .sopcinfo ファイル、--board オプションに指定する .xml ファイルは、プロジェクトやデバイスファミリーによって異なりますが、その他は同様の指定で実行可能です。
--output に指定したファイル名で .dts や .dtb が生成されます。
デバイスツリー・ソース（.dts）を生成
$ sopc2dts --input soc_system.sopcinfo\
--output socfpga.dts\
--type dts\
--board soc_system_board_info.xml\
--board hps_common_board_info.xml\
--bridge-removal all\
--clocks
デバイスツリー・ブロブ（.dtb）を生成
$ sopc2dts --input soc_system.sopcinfo\
--output socfpga.dtb\
--type dtb\
--board soc_system_board_info.xml\
--board hps_common_board_info.xml\
--bridge-removal all\
--clocks
方法2: Linux ソースツリーを使用して make コマンドで作成する
続いて、Linux 開発一般で使用される make コマンドを利用した方法を紹介します。この方法は、Linux ソースツリーをベースにデバイスツリーを生成するため、生成されるデバイスツリーと Linux カーネルバージョンとの互換性の不一致を心配する必要が無く最もお勧めです。
Stratix® 10 SoC では、この方法が標準となります。
2-1: クロスコンパイラーの準備（初回のみ）
この方法を使用するには、Linux ソースツリーのビルド環境が構築できている必要があります。具体的には Arm ターゲット用のクロスコンパイラーのインストールを行います。すでに環境構築済みの場合は本手順は必要ありません。
以下、Linaro（linaro.org）が公開している arm linux 用のクロスコンパイラーをインストールする例です。
$ cd ~
$ wget https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/arm-linux-gnueabihf/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
$ tar Jxf gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
2-2: Linux ソースツリーの準備およびコンフィグ
Linux ソースツリーは別途用意します。以下の例では home ディレクトリー以下 sources/linux-socfpga-4.14.73-ltsi にソースツリーが展開されている前提で記載します。
ソースツリーの Top ディレクトリーへ移動した上で、クロスコンパイラー（CROSS_COMPILE）、ビルド対象アーキテクチャー（ARCH）の 指定を行うための環境変数をセットアップします（クロスコンパイラーは 2-1 のインストール例に従った場合のパスで記載）。
続けて、make clean、make socfpga_defconfig を実行し、SoC FPGA 向けのデフォルト・コンフィグレーションが適用された状態にします。
$ cd ~/sources/linux-socfpga-socfpga-4.14.73-ltsi
$ export CROSS_COMPILE=~/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-
$ export ARCH=arm
$ make clean
$ make socfpga_defconfig
2-3: make 実行
Linux ソースツリーには arch/arm/boot/dts ディレクトリー以下にデバイスツリー・ソース（.dts および .dtsi）が格納されています。.dts と .dtsi の違いは次の通りです。
- .dts ... デバイスツリー・ソース本体（特定のボード向けのデバイスツリー・ソース）
- .dtsi ... デバイスツリー・ソースの部分定義。他の .dts/.dtsi からインクルードされる前提のファイル（特定デバイス向けの共通定義が記述されることが多い）。
以下のように特定の .dts ファイルの拡張子を .dtb に置き換えたファイル名を指定して make を実行することで指定したデバイスツリー・ブロブ（.dtb）が生成されます。
特定のファイル名を指定せず make dtbs を実行することで、SoC FPGA デバイスをターゲットとする全てのデバイスツリー・ソース（.dts）を対象にデバイスツリー・ブロブ（.dtb）を生成することもできます。
予めソースが用意されているデバイスツリーは、上記のいずれかの方法で生成できます。
2-4: （補足）オリジナルのデバイスツリーの作成
Linux ソースツリー以下（arch/arm/boot/dts）に用意されているファイルをベースにオリジナルのデバイスツリー・ソース（.dts）を作成することで、2-3 に記載した方法でオリジナルの .dtb も作成可能です。
尚、オリジナルの .dts を追加した場合には arch/arm/boot/dts/Makefile の編集も必要となります。下記の赤枠にリストされる .dtb ファイルのリストに、新たに追加したデバイスツリー・ソースから生成される .dtb ファイルを追加します。
方法3: dtc を使用して作成および編集する
最後に記載する方法では SoC EDS に付属するデバイスツリー・コンパイラー（dtc）を使用します。dtc を使用することで、デバイスツリー・ソース（.dts）とデバイスツリー・ブロブ（.dtb）の相互変換が可能です。
以下のような用途に利用できます。
- テキスト形式で作成/編集した .dts を Linux が認識可能な形式（.dtb）に変換。
- 既存の .dtb を .dts に変換して内容を確認（.dts を編集後、再度 .dtb に変換する事も可能）。
注記：
.dtsi をインクルードするような複数ファイル構成のデバイスツリー・ソースには、この方法は適用できません。複数ファイル構成のソースは方法2で対応してください。
3-1: 準備
Embedded Command Shell を起動することで利用できます。Shell 起動後にデバイスツリー・ファイル（.dts or .dtb）を格納したディレクトリーに移動し、dtc コマンドを実行するのみです（Windows でも使用可能です）。
Shell の起動は、Linux ホスト環境では下の例のように embedded_command_shell.sh を実行。Windows ホスト環境ではスタートメニューから SoC EDS Command Shell をクリックします。
$ ~/intelFPGA/18.1/embedded/embedded_command_shell.sh
3-2: dtc 実行
基本的には、3つのオプションと入力ファイルを指定するのみで実行可能です。以下の形式で、 -I, -O オプションに入出力ファイルの形式（dts or dtb）、-o オプションに出力ファイル名を指定します。
$ dtc -I <入力形式> -O <出力形式> -o <出力ファイル> <入力ファイル>
.dts から .dtb を生成する場合のコマンドライン例：
$ dtc -I dts -O dtb -o soc_system.dtb soc_system.dts.dtb から .dts を生成する場合のコマンドライン例：
$ dtc -I dtb -O dts -o soc_system.dts soc_system.dtb
3-3: （補足）dtc ヘルプ表示
参考までに dtc のヘルプ表示も掲載しておきます。基本は 3-2 に記載の2通りで対応頂けるはずですが、3-2 に記載したオプション以外にも多くのオプション指定が用意されているようです。必要に応じてお試しください。
まとめ
デバイスツリーの生成/編集の方法について３通りの方法を紹介しましたが、お勧めは 方法2 に記載した Linux ソースツリーをベースに作成する方法です。実際にどの方法で対応するかはユーザーの自由となりますが、選択に悩んだ場合は 方法2 でご対応頂くことをお勧め致します。