はじめに
MBV32用ZephyrでAXI Quad SPIを利用する手順について記述します。
ここではPMOD接続のNOR FLASHを制御します。
SPI対応状況
MBV32の開発ではXSAファイルからDevicetreeを自動生成するのですが、SPI Controllerに関しては自動生成の対象外となっており、標準対応では無さそうです。
ドライバは用意されているので、自前でDevicetreeを追加すれば利用可能です。
AXI Quad SPIドライバの制限事項
現状のドライバはStandard modeのみ対応しています。送受信信号幅は1-bit固定です。
開発環境
Board
Digilent社 BASYS3
NOR Flash Memory
Digilent社 Pmod SF3
Tools
Vivado 2025.1
Vitis 2025.1
Zephyr RTOS
Base Version - 3.7.0
Xilinx Repository Branch - xlnx_rel_v2025.1
Host OS
Ubuntu 24.04 Desktop
今回の作業でVitisは使いませんが、System Device Treeを生成する際にVitisに含まれるツールやデータを利用する為、Vitisのインストールが必要です。
システム概要
Block Design
以下は実装するBlock Designです。
周辺デバイスは以前の記事の実装にSPIコントローラーを追加した形になっています。この他、割り込み線の接続順序を変更してあります。
SPIの信号線はBASYS3のPMOD-Aに接続します。
SPIのピンアサイン
PMOD-Aのピンアサインは以下の通りです。
今回の実装では以下の4ピンをNOR FLASHモジュールに接続します。
JA1 - ~CS
JA2 - MOSI/DQ0
JA3 - MISO/DQ1
JA4 - SCK
JA8 - RST
JA9 - W/DQ2
JA10 - HLD/DQ3
JA1-JA4をBlock Design上のaxi_quad_spi_0に接続、JA8-JA10はaxi_gpio_spiに接続します。
DQxという表記はQuad Modeで利用する際の信号線なので今回は関係ありません。
Vivado/Vitis
これらのツールは/tools/Xilinx/2025.1/配下にインストールされている事を前提とします。
Vivadoのプロジェクトはスクリプトにより$HOME/ws/vivado/basys3-mbv32-spi-nor/配下に作成されます。
Zephyr RTOS
Zephyr RTOSはZephyr ProjectがLTS版としてリリースしている3.7.0にAMDが提供するソースを組み込んだ環境でビルドします。
本記事では$HOME/zephyrproject/配下にインストールされている事を前提とします。
作業手順
前準備
Zephyr Getting Started Guideに記載されている通り、最初はZephyr 3.7.0 Getting Started Guideの手順を実行してビルド環境を用意して下さい。
Install the Zephyr SDKに記載されている手順まで実行します。最後に記述されているudev rulesのインストールは実行しなくても問題ありません。
次に作業に利用するファイル名、ディレクトリ名を定義します。作業環境に合わせて修正して下さい。
# parameters
PROJ_NAME=basys3-mbv32-spi-nor
XSA_FILE=$HOME/ws/vivado/$PROJ_NAME/$PROJ_NAME.xsa
SDT_DIR=$HOME/${PROJ_NAME}_sdt
オリジナルのソースツリーにBASYS3固有のソースツリーを追加します。
最初にpythonのvenvを有効化します。インストール手順の実行直後や実行済みの場合は不要です。
source $HOME/zephyrproject/.venv/bin/activate
次にMicroBlaze-V固有のソースツリーを追加します。
cd $HOME/zephyrproject/
mv zephyr zephyr.upstream
git clone https://github.com/Xilinx/zephyr-amd.git -b xlnx_rel_v2025.1 zephyr
west update
west lopper-install
サンプルコード展開
Zephyr及びVivado Block Designを作成するコード一式をGitHubから入手して下さい。
ソースコードは$HOME/zephyrproject/zephyr/apps/配下に展開します。
mkdir -p $HOME/zephyrproject/zephyr/apps
cd $HOME/zephyrproject/zephyr/apps
git clone https://github.com/hkato-sssl/mbv32-zephyr-spi-nor.git spi-nor
リポジトリ名が長いのでディレクトリ名はspi-norとします。
VivadoによるXSAファイル作成
展開したソースのvivadoディレクトリ配下にBlock Design作成用のスクリプトがあります。下記コマンドを実行するとプロジェクト作成からXSAファイルの作成まで実行されます。
source /tools/Xilinx/2025.1/Vivado/settings64.sh
cd $HOME/zephyrproject/zephyr/apps/spi-nor/vivado
vivado -mode batch -source basys3-mbv32-spi-nor.tcl
VivadoにBASYS3のボード情報が無い場合、ボード情報のダウンロードで多少時間が掛かります。
コマンドはテキスト・モードで実行されます。vivadoのコマンド引数を下記の様にすると、GUIで実行状況を確認できます。
vivado -source basys3-mbv32-spi-nor.tcl
スクリプトの実行が正常終了するとプロジェクト配下にXSAファイルが生成されます。
Devicetree更新
プロジェクト用DevicetreeをXSAファイルから抽出したDevicetreeで更新します。
# create the SDT files
. /tools/Xilinx/2025.1/Vivado/settings64.sh
xsct -eval "sdtgen set_dt_param -dir $SDT_DIR -xsa $XSA_FILE ; sdtgen generate_sdt"
# update the devicetree for Zephyr Project
cd $HOME/zephyrproject/
LOPPER_DTC_FLAGS="-b 0 -@" west lopper-command -p microblaze_riscv_0 -s $SDT_DIR/system-top.dts -w $HOME/zephyrproject/zephyr
サンプルコードのビルドと実行
ビルド手順は以下の通りです。
cd $HOME/zephyrproject/zephyr/apps/spi-nor
west build -p -b mbv32 .
次にHostPCとTarget BoardをUSBで接続した後、下記コマンドを実行します。
cd $HOME/zephyrproject/zephyr/apps/spi-nor
west flash --runner xsdb --elf-file ./build/zephyr/zephyr.elf --bitstream $SDT_DIR/$PROJ_NAME.bit
実行に成功するとシリアル上にSHELLの入力プロンプトが表示されます。
*** Booting Zephyr OS build xilinx_v2024.2-111-g986cf11c05ea ***
uart:~$
プロンプトが表示されたらdevice listコマンドを実行してみて下さい。全デバイスがREADYと表示されれば問題ありません。
uart:~$ device list
devices:
- timer@41c00000 (READY)
- clk_bus_0 (READY)
- clk_cpu (READY)
- interrupt-controller@41200000 (READY)
- gpio_spi (READY)
- gpio_led_16bits (READY)
- gpio_push_buttons (READY)
- gpio_dip_switches (READY)
- gpio_7seg_an (READY)
- gpio_7seg_disp (READY)
- serial@40600000 (READY)
- spi@44a00000 (READY)
- flash@0 (READY)
もしflash@0がREADYとなっていない場合、Devicetree内のjedec-idの値と実デバイスのIDが異なる可能性があります。現状の定義は以下の通りです。
flash0: flash@0 {
compatible = "jedec,spi-nor";
...
jedec-id = [20 ba 19];
};
今回SPI APIの利用例としてIDを読み取るspi_nor idコマンドを追加してあります。
uart:~$ spi_nor id
ID - 20 ba 19
上記以外のID値が表示されたら、Devicetreeの変更と再ビルドを実行してみて下さい。
ShellによるFLASH制御コマンド
Zephyrには標準でFLASH制御コマンドが用意されています。コマンドの有効化はprj.confで行います。
CONFIG_SHELL=y
CONFIG_SPI=y
CONFIG_SPI_SHELL=y
CONFIG_SPI_NOR=y
CONFIG_FLASH=y
CONFIG_FLASH_SHELL=y
CONFIG_FLASH_JESD216_API=y
CONFIG_FLASH_XXXでコマンドを有効化しています。
uart:~$ flash
flash: wrong parameter count
flash - Flash shell commands
Subcommands:
erase : [<device>] <page address> [<size>]
read : [<device>] <address> [<Dword count>]
test : [<device>] <address> <size> <repeat count>
write : [<device>] <address> <dword> [<dword>...]
load : [<device>] <address> <size>
page_info : [<device>] <address>
今回利用しているNOR FLASHの容量は32MiBなので、addressは16進数で0-1FFFFFFまで指定可能です。
以下はコマンド実行例です。
uart:~$ flash test flash@0 0 1000
Erase OK.
Write OK.
Verified OK.
Erase-Write-Verify test done.
uart:~$ flash read flash@0 0 20
00000000: 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |........ ........|
00000010: 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f |........ ........|
uart:~$ flash erase flash@0 0
Erase success.
uart:~$ flash read flash@0 0 20
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ........|
00000010: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ........|
flashコマンドに渡すデバイス名はdevice listで表示されるflash@0を指定します。
AXI Quad SPIのBus Clock
今回はAXI Quad SPIのext_spi_clkに20MHzのクロックを接続しています。これを1/2に分周した10MHzでSPI Busを駆動します。分周比はBlock DesignのIPをダブルクリックして指定します。
Devicetree定義
AXI Quad SPI
AXI Quad SPIのDevicetreeは自動生成されないので、自分で作成する必要があります。Devicetreeの追加はboards/mbv32.overlayに記述してあります。
axi_spi0: spi@44a00000 {
status = "okay";
clocks = <&clk_bus_0>;
#address-cells = <0x01>;
#size-cells = <0x00>;
fifo-size = <256>;
reg = <0x44a00000 0x10000>;
compatible = "xlnx,xps-spi-2.00.a";
interrupt-parent = <µblaze_riscv_0_axi_intc>;
interrupts = <2 0>;
xlnx,num-ss-bits = <1>;
xlnx,num-transfer-bits = <8>;
各パラメータの定義値はBlock DesignやIPのConfigurationから決まります。
自作のデザイン用に記載する時は、regとinterruptsの記述に気を付けて下さい。
NOR Flash Memory
SPIに接続されるデバイスは、SPIの子ノードとして定義されます。NOR Flash MemoryのDevicetreeはAXI Quad SPIの子ノードとして定義されています。
flash0: flash@0 {
compatible = "jedec,spi-nor";
reg = <0>;
reset-gpios = <&axi_gpio_spi 2 GPIO_ACTIVE_LOW>;
wp-gpios = <&axi_gpio_spi 1 GPIO_ACTIVE_LOW>;
hold-gpios = <&axi_gpio_spi 0 GPIO_ACTIVE_LOW>;
size = <0x10000000>;
spi-max-frequency = <10000000>;
jedec-id = [20 ba 19];
};
デバイスの認識にはJEDEC IDが一致する必要がありますので、アクセス出来ない時は最初にIDを確認してみて下さい。
Flash Memoryの容量を定義するsizeはビット数を設定するので注意して下さい。誤ってバイト数を設定するとflashコマンドで1/8の領域しかアクセス出来なくなります。
Flash MemoryではSPI I/Fの他に3つの制御線をオプションで利用可能です。
| reset-gpios | リセット |
| wp-gpios | 書き込み禁止(Write Protect) |
| hold-gpios | デバイス停止 |
今回利用したPmod SF3は3つの信号線全てに対応しています。
これらの信号を接続しているGPIO情報を記述すると、ドライバがGPIO APIを使い必要な制御を行います。不要であれば記述する必要はありません。
記述を省略する場合は未接続信号線の扱いに注意して下さい。これらの信号線はActive Lowなので何も接続しないとリセット信号がアサート状態となりデバイスが認識できません。Block Design上でreset, wp, holdの3つはHighの状態に設定して下さい。
バグ対応
割り込みコントローラードライバの置き換え
「Zephyr on MicroBlaze Vで発生した割り込み処理の問題」で触れた問題ですが、実はこの環境で発生しています。動作確認の過程でflash read flash@0 0 2000000を実行した時にシリアル出力が停止する現象が確認されました。
今回のプロジェクトでは修正版のドライバを追加しており、既存のドライバを置き換えています。
修正したドライバをプロジェクトに追加するだけだとシンボル名の2重定義でエラーとなります。これを避ける目的でオリジナル版ドライバのビルドをprj.confで無効化しています。
CONFIG_XLNX_INTC=n
上記記述の削除と修正したソースをビルド対象から外してビルドすると問題が再現します。
おわりに
これでSPIが利用可能になり、Zephyrで可能な事が増えるかと思います。
次のリリースではAXI Quad SPIも標準でDevicetreeを出力して欲しいですね。


