とにかく複雑な Zynq のソフトウェアを Earthly でビルドする

Zynq はソフトウェアだけにフォーカスしても構成するものが多く、動かすまでがとにかく大変です。Zynq UltraScale+ MPSoC をターゲットにして、APU で Linux を動かしつつ、RPU ではベアメタルアプリケーションを動かして相互に通信…とかやっていくのは実際気の遠くなる作業です。おまけに各種ツールが絶妙にアレなので、この規模にもなると edit-build-run のループを回すのに一苦労です。

Zynq に限らず、規模の大きくなったソフトウェアは edit-build-run あるいは build-test-release-deploy 一連のタスクが複雑になりがちです。複数のプログラミング言語やライブラリが絡むために異なるツールを呼び出さないといけなかったり、ビルドした個々のソフトウェアをパッケージするためにビルドツールを伴わないファイル操作などが絡んだり…。クリーンな状態から1度だけの実行を想定したものでよければ適当なスクリプトで解決するかもしれません。でも普段の開発での利用も想定すると、個々のビルドプロセスとその依存関係を適切に管理できたり、キャッシュなどを使って必要なところだけをいい感じにビルドし直してくれたりするもの、言葉にするなら Build automation tool がほしくなってきます。

なにかいいツールがないかなーと探し回り、あるときはいっそ自分で作ってやろうかと考えたこともありました。そんなときに見つけたのが Earthly です。これが自分が探していたものにかなり近く、Zynq ソフトウェアプロジェクトをはじめ様々な用途で使ってみていい感じだったので紹介しようとおもいます。

Earthly

Earthly はコンテナを活用した Build automation tool です。Makefile と Dockerfile を組み合わせたかのような Earthfile を見れば、これがどんなことをしてくれるものなのかすぐにイメージできるんじゃないかなと思います。実際、Earthly は buikdkit をバックエンドに使っていて、Docker の multi-stage build にかなり近い動作をします。各ターゲットはそれぞれ独立したコンテナ環境で実行されるので、ちゃんと設定さえすればどの実行環境でもほぼ同じビルドが再現できますし、ある別のターゲットで作られたものやリポジトリ管理外のファイルを暗黙的に参照してしまうこともありません。また、ターゲット間の依存関係に問題なければ可能な限り並列で実行してくれたり、一度実行したターゲットは自身が依存するファイルや別のターゲットに変更がない限りキャッシュが効いてくれるのもポイントです。これだけの利点がありながら、Earthly の導入作業は基本的には普段の dockerize と同じ感覚なので、個々のビルド方法自体は大きく変えなくてよく、比較的敷居が低いのも強みです。

hoge:
    FROM alpine
    RUN echo "Hoge!" > awesome.txt
    SAVE ARTIFACT awesome.txt

fuga:
    FROM alpine
    RUN echo "Fuga!" > awesome.txt
    SAVE ARTIFACT awesome.txt

myon:
    FROM alpine
    COPY +hoge/awesome.txt a.txt
    COPY +fuga/awesome.txt b.txt
    RUN cat a.txt b.txt > awesome.txt
    SAVE ARTIFACT awesome.txt

Earthly のインストールは、公式の手順の通りビルド済みのバイナリを使うのが簡単です。ただ自分なら不必要に root で作業したくないので、例えばインストール先は ~/.local/bin にして、また /usr 下に書き込もうとしてくる earthly bootstrap --with-autocomplete は実行しないと思います¹。

$ curl -L https://github.com/earthly/earthly/releases/latest/download/earthly-linux-amd64 \
    -o ~/.local/bin/earthly
$ chmod +x $_

インストールが済んだら早速 Earthly を動かしてみます。適当な場所に空のディレクトリを作り、そこに先ほどあげた Earthfile の例を保存してください。Earthfile に定義されたあるターゲットを実行するには earthly +<ターゲット名> を実行します。例えば hoge と fuga を実行するならそれぞれこうなります。

$ earthly +hoge
$ earthly +fuga

ターゲット myon は hoge と fuga で作ったファイルに依存しています。あるターゲットで作ったものを後段のタスクや Earthly 実行ホストに渡すには、そのファイルを SAVE ARTIFACT コマンドで指定します。そして、別のターゲットからそれを参照するには COPY コマンドを使います。

実際に myon を動かしてみると、myon が依存するターゲットである hoge と fuga が実行されようとしたこと、またそれらターゲットは先程ビルドしたばかりなのでキャッシュが参照されたことがわかります。

 2. Build 🔧
————————————————————————————————————————————————————————————————————————————————

      alpine | --> Load metadata linux/amd64
       +fuga | --> FROM alpine
       +fuga | [██████████] 100% resolve docker.io/library/alpine@sha256:bc41182d7ef5ffc53a40b044e725193bc10142a1243f395ee852a8d9730fc2ad
       +fuga | *cached* --> RUN echo "Fuga!" > awesome.txt
       +hoge | *cached* --> RUN echo "Hoge!" > awesome.txt
       +hoge | --> SAVE ARTIFACT awesome.txt +hoge/awesome.txt
       +fuga | --> SAVE ARTIFACT awesome.txt +fuga/awesome.txt
       +myon | --> COPY +hoge/awesome.txt a.txt
       +myon | --> COPY +fuga/awesome.txt b.txt
       +myon | --> RUN cat a.txt b.txt > awesome.txt
      output | --> exporting outputs

Earthly で作られたものを実行ホスト側に持ってくるには earthly --artifact コマンドを使います。myon で作ったファイル awesome.txt をカレントディレクトリ直下の build/ にコピーするならこうなります。コピー先として渡すパスは末尾を必ず / にします。また先程カレントディレクトリと書きましたが、Earthly は相対パス受け取ったとき、それが Earthfile のあるディレクトリを基準としたものと解釈するのにも注意です。ターゲットからコピーするファイルの指定には * が使えます。たぶん Go 製アプリにありがちな filepath.Match を使うやつです。シェルの設定次第では * を glob として展開しちゃう場合があるのでエスケープしておくと安心です。

$ earthly --artifact +myon/awesome.txt ./build/

$ earthly --artifact +myon/\* ./build/

Earthly の主要操作はだいたいこんな感じです。基本的には Dockerfile と同じなので、Docker を使ったことさえあればあまり難しいことはないと思います。

実際に Zynq をターゲットにした何かを作ってみる

L チカ…？

それでは本題、Earthly をどうやって Zynq UltraScale+ のソフトウェアプロジェクトに適用したかです。この紹介にあたって、こんなものを作ってみました。

一言でいえば、特に理由もなく面倒なことをしている L チカの亜種です。RPU で動く LED 制御のベアメタルアプリケーションと APU 上の Ubuntu で動くアプリケーションが IPI (Inter-Processor Interrupt) を飛ばし合います。APU から RPU への IPI で LED 点滅開始、その後 APU が RPU から飛んでくる IPI に応答し続けないと LED は消えてしまうというものです。題材を複雑にしすぎても準備が大変なだけだし、かといって簡単にしすぎてもおもしろくないし…と悩んだ末のものになります。ソースコードはすべて GitHub リポジトリ Tosainu/earthly-zynqmp-example にあり、この記事は 322ce449 をベースに書いています。

ちなみに、FPGA としての機能をほぼ使っていないのでブロックデザインは実質 PS だけです。Ultra96 ちゃん、XCZU3EG-1SBVA484E ちゃんごめんね…

コンテナ内に必要なツールをそろえる

最初に書く Earthfile のターゲットが、ビルドなど全体のタスク実行に必要なツール類をインストールしてベースイメージのように使うものです。ほかのターゲットから FROM +prep みたいにして使います。

必要になるのは RPU と APU で動かすアプリケーションをビルドするクロスコンパイラ、ディスクイメージ作成のためにファイルシステムやパーティションテーブル操作系のツール、そして .xsa から BSP や FSBL, PMUFW などを生成するための Xilinx のツール類です。クロスコンパイラの大半と Xilinx のツール類は、PetaLinux Tools などで使われているらしい xsct-trim から拝借しました。xsct-trim には AArch64 Linux 向けクロスコンパイラは入っていないので、かわりに Ubuntu の crossbuild-essential-arm64 パッケージを使うことにしました。

prep:
    FROM ubuntu:jammy@sha256:20fa2d7bb4de7723f542be5923b06c4d704370f0390e4ae9e1c833c8785644c1
    RUN \
        apt-get update && \
        DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
            autoconf automake bc bison build-essential ca-certificates cmake cpio \
            crossbuild-essential-arm64 curl dbus-x11 dosfstools e2fsprogs fdisk flex gzip \
            kmod libncurses-dev libssl-dev libtinfo5 libtool-bin locales rsync xz-utils zstd && \
        rm -rf /var/lib/apt/lists/* && \
        sed -i 's/^#\s*\(en_US.UTF-8\)/\1/' /etc/locale.gen && \
        dpkg-reconfigure --frontend noninteractive locales
    ARG XSCT_URL=https://petalinux.xilinx.com/sswreleases/rel-v2022/xsct-trim/xsct-2022-1.tar.xz
    ARG XSCT_SHA256SUM=e343a8b386398e292f636f314a057076e551a8173723b8ea0bc1bbd879c05259
    RUN --mount=type=tmpfs,target=/tmp \
        curl --no-progress-meter -L "${XSCT_URL}" -o /tmp/xsct.tar.xz && \
        echo "${XSCT_SHA256SUM} /tmp/xsct.tar.xz" | sha256sum -c - && \
        mkdir -p /opt/xsct && \
        tar xf /tmp/xsct.tar.xz -C /opt/xsct --strip-components=2
    ENV PATH="/opt/xsct/bin:/opt/xsct/gnu/aarch64/lin/aarch64-none/bin:/opt/xsct/gnu/armr5/lin/gcc-arm-none-eabi/bin:/opt/xsct/gnu/microblaze/lin/bin:${PATH}"
    WORKDIR /build

今回は Earthfile の中にこうしたターゲットを書いていますが、よりビルドの再現性を重視したいのであれば別のアプローチを取るべきです。apt-get などのコマンドは、パッケージの更新などのために実行するタイミングで結果が大きく変わりうるためです。対策の一例としては、この部分だけ独立したコンテナイメージ化し、レジストリで管理するなどがあると思います。

xsct-trim で FSBL, PMUFW, BSP, Devicetree を出力させる

次は FSBL、PMUFW、RPU ベアメタルアプリケーションの BSP、そして Devicetree のテンプレートなど、Vitis でいう platform に相当するものたちを xsct-trim に入っている XSCT に出力させます。

いつもの XSCT コマンドを並べた TCL スクリプトを作っておきます。コマンドラインから .xsa ファイルのパスを受け取ったり、Earthfile 側から .bit ファイルを常に同じファイル名で扱えるように symlink を張るようにもしておきます。

set xsa_file [lindex $argv 0]

hsi open_hw_design $xsa_file

set bit_file [lindex [hsi get_hw_files -filter {TYPE==bit}] 0]
file link -symbolic system.bit $bit_file

hsi set_repo_path embeddedsw

hsi create_sw_design fsbl -proc psu_cortexa53_0 -os standalone
hsi set_property CONFIG.stdin  psu_uart_1 [hsi get_os]
hsi set_property CONFIG.stdout psu_uart_1 [hsi get_os]
hsi add_library xilffs
hsi add_library xilpm
hsi add_library xilsecure
hsi generate_app -app zynqmp_fsbl -dir fsbl
hsi close_sw_design [hsi current_sw_design]

hsi create_sw_design pmufw -proc psu_pmu_0 -os standalone
hsi set_property CONFIG.stdin  psu_uart_1 [hsi get_os]
hsi set_property CONFIG.stdout psu_uart_1 [hsi get_os]
hsi add_library xilfpga
hsi add_library xilsecure
hsi add_library xilskey
hsi generate_app -app zynqmp_pmufw -dir pmufw
hsi close_sw_design [hsi current_sw_design]

hsi create_sw_design bsp_psu_cortexr5_0 -proc psu_cortexr5_0 -os standalone
hsi set_property CONFIG.stdin  psu_uart_1 [hsi get_os]
hsi set_property CONFIG.stdout psu_uart_1 [hsi get_os]
# hsi add_library xilffs
# hsi add_library xilfpga
# hsi add_library xilmailbox
# hsi add_library xilpm
# hsi add_library xilsecure
# hsi add_library xilskey
hsi generate_bsp -dir bsp_psu_cortexr5_0
hsi close_sw_design [hsi current_sw_design]

hsi set_repo_path device-tree-xlnx

hsi create_sw_design device-tree -proc psu_cortexa53_0 -os device_tree
hsi set_property CONFIG.console_device psu_uart_1 [hsi get_os]
hsi generate_target -dir device-tree

あとはこれを xsct に実行させれば OK です。ビルド時に可変なパラメータを宣言する ARG で .xsa ファイルへのパスを渡せるようにしておきます。生成したファイルは全部 SAVE ARTIFACT して別のターゲットから取り出せるようにしておきます。FSBL, PMUFW, BSP のビルドはそれぞれ独立したターゲットにして、ターゲット単位のビルド並列化が効くようにします²。

generate-src:
    ARG --required XSA_FILE

    FROM +xsct
    COPY generate.tcl .
    COPY $XSA_FILE system.xsa
    RUN USER="$(id -u -n)" xsct -sdx -nodisp generate.tcl system.xsa
    SAVE ARTIFACT bsp_psu_cortexr5_0
    SAVE ARTIFACT device-tree
    SAVE ARTIFACT fsbl
    SAVE ARTIFACT pmufw
    SAVE ARTIFACT system.bit

fsbl.elf:
    FROM +prep
    COPY +generate-src/fsbl .
    RUN make
    SAVE ARTIFACT executable.elf /fsbl.elf

pmufw.elf:
    FROM +prep
    COPY +generate-src/pmufw .
    RUN make CFLAGS="-DENABLE_MOD_ULTRA96 -DULTRA96_VERSION=2 -DPMU_MIO_INPUT_PIN_VAL=1 -DBOARD_SHUTDOWN_PIN_VAL=1 -DBOARD_SHUTDOWN_PIN_STATE_VAL=1"
    SAVE ARTIFACT executable.elf /pmufw.elf

bsp-r5-0:
    FROM +prep
    COPY +generate-src/bsp_psu_cortexr5_0 .
    RUN make
    SAVE ARTIFACT psu_cortexr5_0/include /include
    SAVE ARTIFACT psu_cortexr5_0/lib/*a /lib/

RPU と APU のアプリケーション

RPU アプリケーションは、素直に Vitis を使ってテンプレートプロジェクトを作りました。xsct-trim と Xilinx/embeddedsw の組み合わせでは standalone のテンプレートが出てこなかったためです。でもアプリケーションのビルドは Vitis ではなく自分たちでやりたいので、lscript.ld など必要なものだけを持ってくるのと、コンパイラに渡しているオプションの確認が済んだら Vitis の出番は終了です。

コードは CMake でビルドできるようにしました。FindLibXil.cmake を書いたので、libxil.a などを find_package() で探せるようになっています。BSP をビルドしたターゲット bsp-r5-0 からライブラリとヘッダファイルをコピーしてきて、それを FindLibXil.cmake が探せるように -DLibXil_ROOT= でパスを渡します。またクロスコンパイラを使ってビルドするために、CMake に toolchain file を渡して指示します。CMake は -S, -B, -DLibXil_ROOT などがカレントディレクトリからの相対パスを受け付けてくれるのに対して、--toolchain は絶対パス、またはビルドディレクトリ・ソースディレクトリからの相対パスを要求してくるのに注意です。

app-r5-0:
    FROM +prep
    COPY +bsp-r5-0/ libxil
    COPY apps/r5_0 src
    COPY apps/toolchain/armr5-none-eabi.cmake .
    RUN cmake \
        --toolchain $PWD/armr5-none-eabi.cmake \
        -S src \
        -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_INSTALL_PREFIX=install \
        -DLibXil_ROOT=libxil
    RUN cmake --build build -- install
    SAVE ARTIFACT install/* /

APU のアプリケーションも C++ で書いて CMake でビルドします。RPU と違って標準ライブラリと Linux の機能しか使わないので、クロスコンパイルのために toolchain file を渡す以外は特別な設定もなくいつもどおりです。

app-a53:
    FROM +prep
    COPY apps/a53 src
    COPY apps/toolchain/aarch64-linux-gnu.cmake .
    RUN cmake \
        --toolchain $PWD/aarch64-linux-gnu.cmake \
        -S src \
        -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_INSTALL_PREFIX=install/usr
    RUN cmake --build build -- install
    SAVE ARTIFACT install/* /

Linux カーネルの .deb パッケージ

組み込みで Linux を使うなら、やっぱりカーネルのコンフィグはプロジェクト単位で細かく設定したいです。ということでカーネルも一緒にビルドします。今回作る Linux 環境は Ubuntu なので、make bindeb-pkg で .deb パッケージを作ることにしました。

カーネルのコンフィグファイルは実行環境に依存しない defconfig 形式を使うのが望ましいのですが、手抜きをして menuconfig で作ったものをそのままリポジトリに入れています。SAVE ARTIFACT するのは作った .deb パッケージと、あとで .dts をコンパイルするときに使うヘッダファイルです。

linux:
    FROM +prep
    RUN --mount=type=tmpfs,target=/tmp \
        curl --no-progress-meter -L https://github.com/Xilinx/linux-xlnx/archive/75872fda9ad270b611ee6ae2433492da1e22b688.tar.gz -o /tmp/archive.tar.gz && \
        echo '75e40c693484710cd7fc5cd972adb272414d196121c66a6ee2ca6ef762cb60c9  /tmp/archive.tar.gz' | sha256sum -c && \
        tar xf /tmp/archive.tar.gz --strip-components=1
    COPY linux/.config .
    ARG nproc=$(nproc)
    RUN CROSS_COMPILE=aarch64-linux-gnu- make -j$nproc ARCH=arm64 bindeb-pkg
    SAVE ARTIFACT include/dt-bindings /include/dt-bindings
    SAVE ARTIFACT /*.deb

Ubuntu の rootfs

今回のアプリケーションを動かす環境として、Ubuntu は完全にオーバーキルです。それどころかブート時間やデータ量などの面でマイナスです。それでも Ubuntu にしたのは、構築後もその上で変更を加えられて、デスクトップ用途でも使ったことがあるだろう環境が動いてほしいという風潮を感じたためです。Linux From Scratch 的なことをしはじめると crossbuild-essential-arm64 と少し相性が悪くなってくるのと、単純に説明が面倒になるからというのもあります。

Ubuntu 環境の構築には mmdebstrap を使ってみました。よく知られた debootstrap と比較して、処理時間が早いことや、より小さな環境を作りやすかったりするのがウリだそうです。

rootfs-base.tar:
    FROM --platform=linux/arm64 ubuntu:jammy@sha256:1bc0bc3815bdcfafefa6b3ef1d8fd159564693d0f8fbb37b8151074651a11ffb
    RUN apt-get update && \
        apt-get install -y --no-install-recommends mmdebstrap && \
        rm -rf /var/lib/apt/lists/*
    COPY +linux/*.deb kernels/
    RUN mmdebstrap \
        --verbose \
        --components='main restricted universe multiverse' \
        --variant='minbase' \
        --include='apt dbus e2fsprogs init iproute2 iputils-ping kmod libstdc++6 parted sudo systemd-timesyncd udev' \
        --customize-hook='cp -r kernels "$1/" && chroot "$1" sh -c "dpkg -i /kernels/*.deb" && rm -rf "$1/kernels"' \
        --customize-hook='sed -i "s/^#\s*\(%sudo\)/\1/" "$1/etc/sudoers"' \
        --customize-hook='chroot "$1" adduser --disabled-password user' \
        --customize-hook='chroot "$1" adduser user sudo' \
        --customize-hook='echo "user:user" | chroot "$1" chpasswd' \
        --customize-hook='chroot "$1" passwd --expire user' \
        --customize-hook='chroot "$1" passwd --lock root' \
        --dpkgopt='path-exclude=/usr/share/man/*' \
        --dpkgopt='path-include=/usr/share/man/man[1-9]/*' \
        --dpkgopt='path-exclude=/usr/share/locale/*' \
        --dpkgopt='path-include=/usr/share/locale/locale.alias' \
        --dpkgopt='path-exclude=/usr/share/doc/*' \
        --dpkgopt='path-include=/usr/share/doc/*/copyright' \
        jammy rootfs-base.tar http://ports.ubuntu.com/ubuntu-ports
    # Use .tar format since SAVE ARTIFACT and COPY drop permissions for some reason even specifying with the --keep-own option...
    SAVE ARTIFACT rootfs-base.tar

これまでのターゲットと違い、FROM には --platform=linux/arm64 を渡して 64 bit ARM の Ubuntu が設定されています。Earthly にビルドさせる前に qemu-user-static と binfnt_misc を設定しておきましょう。mmdebstrap にこれを勝手にやってくれる機能もあるようですが、Earthly の起動するコンテナ内でやってもらおうとするとたぶん --privileged が必要なので使っていません。mmdebstrap 出力形式はディレクトリではなく .tar にしています。SAVE ARTIFACT や COPY にディレクトリを渡したとき、-–keep-own を渡したとしてもファイルのオーナーが root に変わってしまう現象があったためです。ちなみに無圧縮な .tar なのは時間短縮のためです。このターゲット内での処理は QEMU を介して動いてしまうのを忘れてはいけません³。

mmdebstrap は、--customize-hook= などのコマンドラインオプションで構築中の環境に対して任意のコマンドを実行できます。しかし、このターゲット内でのカスタマイズは最低限のもの、具体的には chroot を介さないと難しいものだけにとどめています。これは、なにか変更をしようとしたときに毎回 mmdebstrap が走ってしまうのを防ぐためです。いくら mmdebstrap が速さをアピールしているといえ、ファイル追加といった簡単なタスクに対しても毎回 mmdebstrap が走ってしまうのはかなり不便なので。

作った Ubuntu の .tar にファイルの追加をしているのがこのターゲットです。追加するのは APU のアプリケーションやその他設定ファイル類です。ファイルを追加するだけなら tar を展開しなくてもできます。

rootfs.tar:
    FROM +prep
    COPY +rootfs-base.tar/rootfs-base.tar rootfs.tar
    COPY linux/rootfs rootfs
    COPY +app-a53/ rootfs
    RUN tar --append -f rootfs.tar --xattrs --xattrs-include='*' -C rootfs .
    SAVE ARTIFACT rootfs.tar

U-Boot

U-Boot のビルドは、ARCH に渡す値が aarch64 に変わるくらいで Linux とほぼ同じです。ビルドで一緒に作られるツール dtc と mkimage がこの後の作業で必要なので、これらも忘れず SAVE ARTIFACT しておきます。

u-boot:
    FROM +prep
    RUN --mount=type=tmpfs,target=/tmp \
        curl --no-progress-meter -L https://github.com/Xilinx/u-boot-xlnx/archive/refs/tags/xilinx-v2022.1.tar.gz -o /tmp/archive.tar.gz && \
        echo 'a02adc8d80f736050772367ea6f868214faaf47b6b3539781d6972dab26b227c  /tmp/archive.tar.gz' | sha256sum -c && \
        tar xf /tmp/archive.tar.gz --strip-components=1
    ARG nproc=$(nproc)
    COPY u-boot.config .config
    RUN CROSS_COMPILE=aarch64-linux-gnu- ARCH=aarch64 \
        make -j$nproc u-boot.elf
    SAVE ARTIFACT u-boot.elf
    SAVE ARTIFACT scripts/dtc/dtc /dtc
    SAVE ARTIFACT tools/mkimage /mkimage

Linux と同様に、コンフィグはこちらも menuconfig で作ったものをそのまま入れています。ちなみにこのコンフィグは xilinx_zynqmp_virt_defconfig をベースに使わない機能を削り、U-Boot 自身が使う Devicetree Blob をどうロードするかを変更したものです。Devicetree は FSBL にロードさせたいので CONFIG_OF_BOARD に変更しています。

Device Tree Control  --->
    Provider of DTB for DT control (Provided by the board (e.g a previous loader) at runtime)  --->
        (X) Provided by the board (e.g a previous loader) at runtime

Trusted Firmware-A (TF-A)

以前は arm-trusted-firmware やそれを略して ATF と呼ばれていたやつです。これもいつもどおりの方法でビルドします。ZYNQMP_CONSOLE=cadence1 をつけるとメッセージ出力先が UART1 になってくれます。

tf-a:
    FROM +prep
    RUN --mount=type=tmpfs,target=/tmp \
        curl --no-progress-meter -L https://github.com/Xilinx/arm-trusted-firmware/archive/refs/tags/xilinx-v2022.1.tar.gz -o /tmp/archive.tar.gz && \
        echo 'e7d6a4f30d35b19ec54d27e126e7edc2c6a9ad6d53940c6b04aa1b782c55284e  /tmp/archive.tar.gz' | sha256sum -c && \
        tar xf /tmp/archive.tar.gz --strip-components=1
    ARG nproc=$(nproc)
    RUN CROSS_COMPILE=aarch64-linux-gnu- ARCH=aarch64 \
        make -j$nproc PLAT=zynqmp RESET_TO_BL31=1 ZYNQMP_CONSOLE=cadence1
    SAVE ARTIFACT build/zynqmp/release/bl31/bl31.elf /

Devicetree Blob

XSCT で生成した .dts に必要なものを追記して、それを U-Boot と Linux の両方にロードさせることにします。gcc はプリプロセッサを処理するために呼んでいます。渡しているオプションは Linux カーネルにならったものです。

system.dtb:
    FROM +prep
    COPY +generate-src/device-tree .
    COPY +linux/include include
    COPY +u-boot/dtc .
    COPY system-top-append.dts .
    RUN cat system-top-append.dts >> system-top.dts && \
        gcc -E -nostdinc -undef -D__DTS__ -x assembler-with-cpp -Iinclude -o - system-top.dts | ./dtc -@ -p 0x1000 -I dts -O dtb -o system.dtb
    SAVE ARTIFACT system.dtb

Bootgen と boot.bin

boot.bin の生成に使う bootgen は GitHub にソースコードがあります。まずこれをビルドします。ソースコードを持ってきて make すれば、同じディレクトリ内に実行ファイル bootgen が出来上がります。

bootgen:
    FROM +prep
    RUN --mount=type=tmpfs,target=/tmp \
        curl --no-progress-meter -L https://github.com/Xilinx/bootgen/archive/refs/tags/xilinx_v2022.1.tar.gz -o /tmp/archive.tar.gz && \
        echo 'a7db095abda9820babbd0406e7036d663e89e8c7c27696bf4227d8a2a4276d13  /tmp/archive.tar.gz' | sha256sum -c && \
        tar xf /tmp/archive.tar.gz --strip-components=1
    RUN make
    SAVE ARTIFACT bootgen

次に boot.bin に含めるファイルとその構成を指示する .bif ファイルを作ります。ここに書いた system.dtb は U-Boot が使うものです。ロード先のアドレス 0x100000 は U-Boot の CONFIG_XILINX_OF_BOARD_DTB_ADDR=0x100000 に対応しています。UG1283 にある通り、PMUFW のロードのさせ方には [pmufw_image] と [destination_cpu=pmu] の2通りあり、その違いは BootROM にロードさせるか FSBL にロードさせるかです。BootROM にロードさせると PMUFW 実行直後のバージョンなどの方法が出てこない気がする⁴ので FSBL にロードさせています。

all:
{
  [destination_cpu=a53-0, bootloader]                       fsbl.elf
  [destination_cpu=pmu]                                     pmufw.elf
  [destination_device=pl]                                   system.bit
  [destination_cpu=a53-0, exception_level=el-3, trustzone]  bl31.elf
  [destination_cpu=a53-0, exception_level=el-2]             u-boot.elf
  [destination_cpu=a53-0, load=0x100000]                    system.dtb
  [destination_cpu=r5-lockstep]                             ipi-led.elf
}

あとはこれまでのターゲットでビルドしてきた必要なファイルと .bif ファイルを持ってきて、bootgen コマンドを実行すれば OK です。

boot.bin:
    FROM +prep
    COPY +app-r5-0/bin/ipi-led.elf .
    COPY +bootgen/bootgen .
    COPY +fsbl.elf/ .
    COPY +generate-src/system.bit .
    COPY +pmufw.elf/ .
    COPY +system.dtb/ .
    COPY +tf-a/bl31.elf .
    COPY +u-boot/u-boot.elf .
    COPY boot.bif .
    RUN ./bootgen -arch zynqmp -image boot.bif -o boot.bin
    SAVE ARTIFACT boot.bin

boot.scr

U-Boot には、ブートデバイスのファイルシステム直下にあるスクリプト boot.scr を実行してくれる機能があります。これを使ってカーネルがある場所を指示したり、ロードしたカーネルでブートさせたりします。boot.scr は、U-Boot のコマンドをテキストファイルに書き、mkimage に渡して作ります。

boot.scr:
    FROM +prep
    COPY +u-boot/mkimage .
    COPY boot.cmd .
    RUN ./mkimage -c none -A arm64 -T script -d boot.cmd boot.scr
    SAVE ARTIFACT boot.scr

ブートデバイスとして使う SD カードには2つのパーティションを作り、1つ目のパーティションに boot.bin, boot.scr, system.dtb を、2つ目のパーティションに Ubuntu ということにします。開発時の書き換えやすさを優先して、system.dtb も1つ目のパーティションに置いています。ということで boot.cmd はこんな感じです。カーネルは2つ目のパーティションの /boot にあるので mmc 0:2 ..., system.dtb は1つ目のパーティション直下にあるので mmc 0:1 ... になります。あとはファイルをロードしたアドレスを booti コマンドに渡してブートさせます。initramfs を使わないので、booti の第2引数は - にします。

load mmc 0:2 ${kernel_addr_r} /boot/vmlinuz-5.15.19
load mmc 0:1 ${fdt_addr_r} /system.dtb
booti ${kernel_addr_r} - ${fdt_addr_r}

ちなみに、bindeb-pkg で作ったカーネルの .deb パッケージは、Linux カーネルに含まれる .dts から作った .dtb を /usr/lib/linux-image-* にインストールするようです。カーネルにあるもので十分なケースではこちらのパスを設定すればよいです。

SD カードのディスクイメージも作っちゃう

ここまでで必要なファイルが全て揃いました。でも、これですぐ Ultra96 で動かせるかといえば ✗ です。SD カードにパーティションを切って、それぞれフォーマットして、ファイルをコピーして…と、地味に面倒な作業が残っています。少しでも作業を減らすために、Earthfile の中で SD カードのディスクイメージまで作ってしまいます。

最初にパーティション毎にイメージを作ってフォーマット & データのコピー、最後にそれらを結合して sfdisk でパーティションテーブルの書き込み、という感じのことをやっています。loop デバイスの作成や mount などを実行しているため、ここだけは仕方なく --privileged をつけています。いきなりディスクイメージを作らずパーティション毎にファイルを分けて構築しているのは、コンテナ内で mount は動くけど losetup はうまく動いてくれない場合があったことと、そもそもカーネルモジュール loop のパラメータ max_part が指定しなければ大抵0なため、パーティションを持つ loop デバイスの作成がコンテナ内だけの処理で完結しにくいためです。

disk.img.zst:
    FROM +prep
    COPY +boot.tar/ .
    COPY +rootfs.tar/ .
    ARG DISK_IMG_PART1_SIZE=16M
    ARG DISK_IMG_PART2_SIZE=256M
    RUN --mount=type=tmpfs,target=/tmp --privileged \
        truncate -s "$DISK_IMG_PART1_SIZE" /tmp/boot.img && \
        mkfs.vfat -F 16 /tmp/boot.img && \
        mount /tmp/boot.img /mnt && \
        tar xf boot.tar -C /mnt && \
        umount /mnt && \
        truncate -s "$DISK_IMG_PART2_SIZE" /tmp/root.img && \
        mkfs.ext4 /tmp/root.img && \
        mount /tmp/root.img /mnt && \
        tar xf rootfs.tar --xattrs --xattrs-include='*' -C /mnt && \
        umount /mnt && \
        truncate -s 1M /tmp/header.img && \
        cat /tmp/header.img /tmp/boot.img /tmp/root.img > /tmp/disk.img && \
        echo "label: dos\n1M,${DISK_IMG_PART1_SIZE},e\n,${DISK_IMG_PART2_SIZE},L\n" | sfdisk /tmp/disk.img && \
        zstd --no-progress -9 /tmp/disk.img -o disk.img.zst
    SAVE ARTIFACT disk.img.zst

boot.tar:
    FROM +prep
    COPY +boot.scr/boot.scr boot/
    COPY +boot.bin/ boot/
    COPY +system.dtb/ boot/
    RUN tar --create -f boot.tar -C boot .
    SAVE ARTIFACT boot.tar

もちろんディスクイメージを作ったからといって、なにか変更を加えたときに毎回焼き直す必要はありません。例えば RPU のアプリケーションや Devicetree を変更しただけなら第1パーティションだけ、といった感じに2回目以降は変更があった箇所だけ書き直せば十分です。またせっかく載せたリッチな Linux 環境を活用して、USB メモリやネットワーク経由でファイルが転送できると思います。APU のアプリケーションは、何かしらの修正を加えたものをシュッと転送してすぐ試す、ができます。

もちろん Ultra96 は SD カードからしかブートできないわけではありません。JTAG を使ってロードし直すのもアリですね。

ビルド！

Earthly は1回のコマンド実行で1つのターゲットしか呼び出せないので、最終的に必要となるものをまとめるターゲットを作っておくのが便利です。今回の Earthfile では build がこれに対応します。RUN などのコマンドを使わないなら、FROM に scratch が指定できます。

build:
    FROM scratch
    COPY +disk.img.zst/ .

    COPY +app-r5-0/bin/ipi-led.elf .
    COPY +boot.bin/ .
    COPY +boot.scr/ .
    COPY +fsbl.elf/ .
    COPY +generate-src/system.bit .
    COPY +pmufw.elf/ .
    COPY +system.dtb/ .
    COPY +tf-a/bl31.elf .
    COPY +u-boot/u-boot.elf .
    SAVE ARTIFACT ./*

早速このターゲットをビルドします。rootfs-base.tar のために qemu-user-static が準備できていることを再確認した上で次のコマンドを実行します。できたディスクイメージなどはローカルに持ってきたいので --artifact を、--privileged を付けたターゲット disk.img.zst のために --allow-privileged を付けます。

$ earthly --artifact --allow-privileged +build/\* --XSA_FILE=design_1_wrapper.xsa ./build/

あとはこんな感じで disk.img.zst を SD カードに焼けば実機で動かせると思います。

$ zstdcat build/disk.img.zst | sudo dd of=/dev/sdX bs=1M status=progress

GitHub Actions

せっかく Vivado/Vitis を使うことなく (xsct-trim は使っていますが) ビルドできるようになったので、GitHub Actions 上でビルドするようにしてみました。ソフトウェアのパートに絞り、かつ GitHub Actions の設定は最低限のもののみであるとはいえ、あのバージョン管理ツールでさえ導入しにくさに定評のある Xilinx の開発環境を必要とするはずのものが GitHub Actions 上で動いているのは、Earthly 導入の副次効果であるとはいえ大きなことではないかと思います。

今後なんとかしたいこと

デバッグ関連

なんとかできるといいなと思っていることの1つがデバッグです。Earthly でビルドしたバイナリはデバッグシンボルに含まれるファイルパスがコンテナ内のものなので、ホスト側環境のデバッガー等に食わせるとちゃんと認識してくれません。GDB は set substitute-path でファイルパスの置換ができますが、Xilinx の XSDB はできません。単なるマイコンと違って FPGA の bitstream をロードだとかもできてほしいので、じゃあ GDB だけ使おうってわけにもいかないんです。

なんか OpenOCD + GDB で Ultra96 の R5 で動いてるアプリのデバッグいけたっぽい pic.twitter.com/EzRcJhCYyo
— ✧*。ヾ(｡ᐳ﹏ᐸ｡)ﾉﾞ。*✧ (@myon___) August 30, 2022

ビルドをもっと速くしたい

Earthly は、基本的に同じ入力に対するビルドは1回きりで、それ以降はキャッシュを使ってくれます。言い換えれば、何かしらのターゲットが依存するファイルを少しでも変更すれば、その影響を受けた箇所以降を RUN などのコマンド単位で再実行しなくてはいけません。今回の Earthfile だと、例えば Linux カーネルをビルドする linux ターゲットでそれが顕著に出てくると思います。コンフィグを変更しない限り⁵リビルドは起きません。しかしコンフィグを1行だけでも書き換えたのなら、前回のビルド結果の再利用もなく RUN make からやり直しです。RUN –-mount=type=cache や CACHE コマンドを使って追加のキャッシュを設定すれば何とかできたりしますが、同時に制御しづらい状態に依存を作ってしまいます。使いどころがちょっと難しいのですよね⁶。

もう一つビルド高速化に関連して、ターゲット内のビルド実行のジョブ数をどーやって決めるか問題があります。Earthly はターゲット間の依存関係に問題ない限り並列に実行してくれます。しかしターゲットのビルドに見込まれる時間やどれくらいの計算リソースが必要かなどはもちろん考慮してくれません。Earthly の並列実行を見込んでタスク内のジョブ数を減らせは (例えば1)、CPU が暇をしまくっているにもかかわらず時間のかかるターゲット1つだけがのんびり実行されることになったり。逆に $(nproc) などにすれば、一時的に CPU やメモリ、時にはディスクアクセスがすごいことになるのが十分に予想できます。今回は手抜きで $(nproc) を設定している箇所がいくつかあります。GitHub Actions でもメモリ不足で殺されることなく動いているようですし、ThinkPad X13 Gen2 の 16GB RAM と約 6 GB のスワップという環境でも、一瞬スワップの使用量がグンと上がる程度でなんとかなっているのでまぁ許容範囲？です。ブラウザのタブをめっちゃ開いていたらいくつかクラッシュしちゃうかもですが。

おわり

Earthly という Build automation tool の紹介と、それを Zynq のソフトウェアプロジェクトに導入してみた例を紹介しました。Earthly が個々のソフトウェアのビルド方法自体は大きく変えなくてよく比較的簡単に導入できること、そしてコンテナ内でのビルドで様々な恩恵が得られることが伝わればと思います。Zynq に関しては、イマドキできて当たり前の開発ワークフローでさえ導入しづらく苦労していたものが、Earthly のおかげで随分と開発環境を改善できました。

おまけ: 内部実装いろいろ

Zynq UltraScale+ の IPI をそのまま使う

今回の IPI の用途はとても単純なので、この文脈でよく出てくる libmetal や OpenAMP は使っていません。RPU は embeddedsw に含まれる XIpiPsu で、APU 側は Userspace I/O を介して IPI を直接操作しています。

IPI の基本操作 (主要レジスタ) は、割り込みの有効・無効 (IER, IDR)、IPI の Trigger (TRIG)、割り込みを受けたときのステータス確認とクリア (ISR)、割り込みを起こせたか・ターゲットがそれをクリアしたかの確認 (OBS) です。どの操作も、読み書きする値はターゲットの channel に対応するビットマスクです。今回の実装では、RPU 0 をデフォルトの channel 1 に, APU を channel 7 を割り当てました⁷。ビットマスクはそれぞれ 8 bit 目と 24 bit 目がこれに対応します。

ということで、まずは embeddedsw の XIpiPsu を使った RPU 側アプリケーションの例です。XIpiPsu は、レジスタの操作ほぼそのままのインターフェイスを提供しているようです。xparameters.h には channel 7 に相当する XPAR_XIPIPS_TARGET_PSU_CORTEXA53_0_CH0_MASK のような定数がないので、コードのなかで定義しています。

inline constexpr std::uint32_t IPI_TRIG_CH7_MASK = std::uint32_t{1} << 24;

XIpiPsu ipi{};
{
  auto cfg = XIpiPsu_LookupConfig(XPAR_PSU_IPI_1_DEVICE_ID);
  XIpiPsu_CfgInitialize(&ipi, cfg, cfg->BaseAddress);
}

XIpiPsu_InterruptEnable(&ipi, IPI_TRIG_CH7_MASK);       // IER
XIpiPsu_InterruptDisable(&ipi, IPI_TRIG_CH7_MASK);      // IDR
XIpiPsu_TriggerIpi(&ipi, IPI_TRIG_CH7_MASK);            // TRIG
XIpiPsu_ClearInterruptStatus(&ipi, IPI_TRIG_CH7_MASK);  // ISR write (clear)

XIpiPsu_GetInterruptStatus(ipi);  // ISR read
XIpiPsu_GetObsStatus(&ipi)        // OBS

続いて Linux 側です。IPI のレジスタを UIO で使えるように、カーネルは CONFIG_UIO_PDRV_GENIRQ を有効にしておきます。

Device Drivers  --->
    <*> Userspace I/O drivers  --->
        <M>   Userspace I/O platform driver with generic IRQ handling

そして Devicetree に UIO デバイスのノードを追加します。compatible や uio_pdrv_genirq.of_id に設定する文字列は、この界隈の慣習 (?) にならって generic-uio にしています。実際は何でもよいはずです。node-name も名前がかぶらなければ何でもよいと思います。一応 Devicetree Specification には Generic Names Recommendation というセクションがありますが、これに当てはまりそうなものはなさそうです。unit-address は対応するもののベースアドレスにしておくのが無難です。

/ {
  ipi-ctrl@ff340000 {
    compatible = "generic-uio";
    reg = <0x0 0xff340000 0x0 0x1000>;
    interrupt-parent = <&gic>;
    interrupts = <0 29 4>;
  };
};

これで IPI のレジスタなどに /dev/uioN でアクセスできます。実際に操作するコードは例えばこんな感じです。まぁ UIO で見えるようになったレジスタに対して値を読み書きするだけですね。

inline constexpr std::size_t IPI_TRIG = 0; // Interrupt Trigger
inline constexpr std::size_t IPI_OBS = 1;  // Interrupt Observation
inline constexpr std::size_t IPI_ISR = 4;  // Interrupt Status and Clear
inline constexpr std::size_t IPI_IMR = 5;  // Interrupt Mask
inline constexpr std::size_t IPI_IER = 6;  // Interrupt Enable
inline constexpr std::size_t IPI_IDR = 7;  // Interrupt Disable

inline constexpr std::uint32_t IPI_TRIG_RPU0_MASK = std::uint32_t{1} << 8;

int fd = ::open("/dev/uioN", O_RDWR | O_CLOEXEC);

auto reg = static_cast<std::uint32_t*>(
    ::mmap(nullptr, mapsize, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0));

reg[IPI_IER] = IPI_TRIG_RPU0_MASK;   // IER
reg[IPI_IDR] = IPI_TRIG_RPU0_MASK;   // IDR
reg[IPI_TRIG] = IPI_TRIG_RPU0_MASK;  // TRIG
reg[IPI_ISR] = IPI_TRIG_RPU0_MASK;   // ISR write (clear)

const auto isr = reg[IPI_ISR];  // ISR read
const auto obs = reg[IPI_OBS];  // OBS

UIO を使った場合の割り込みはちょっとおもしろいです。open したときの file descriptor に1 (non-zero value) を write すると、割り込みが来たタイミングで read が返ってくるというインターフェイスになっています。読み出した値は使っていませんが、カーネルの実装を見た感じでは割り込み毎に増えていくカウンタのようですね。

for (;;) {
  std::uint32_t irq = 1;

  // 次の read() で割り込みを受け取る
  if (::write(fd &irq, sizeof irq) < 0) {
    std::perror("write");
    return -1;
  }

  // 割り込みを待つ
  if (::read(fd, &irq, sizeof irq) < 0) {
    std::perror("read");
    return -1;
  }

  // 割り込みクリア
  if (reg[IPI_ISR] & IPI_TRIG_RPU0_MASK) {
    reg[IPI_ISR] = IPI_TRIG_RPU0_MASK;
  }
}

さて、これで互いに IPI を飛ばせるようになりました。では IPI を飛ばしたタイミングで何かしらのデータをやりとりしたい場合はどうするかです。今回は Technical Reference Manual (TRM, UG1085) の IPI と同じ場所で言及されている Message Buffer を使いました。Message Buffer は、IPI の requester/responder の組み合わせ1つあたりに request/response それぞれ 32 byte が確保されたメモリ空間です。IPI を使うプロセッサなど (TRM の言葉だと Agent) は8つあるので、Agent 毎に 0x20 * 2 * 8 = 0x200 byte ですね。

この Message Buffer の厄介なところが、ある IPI の request/response でどこを使えばいいのかがわかりにくいところです。channel と buffer index がとてもまぎらわしいし、おまけに TRM に書いてあるアドレスと xparameters.h の値がなんか違う気がします。今回の構成における値をxparameters.h の値をもとに表にしてみました。環境・構成によっては変わってくるかもしれないことに注意です。

Channel Number	Owner	Message Buffer Index	Address
Channel 0	APU	2	`0xff99'0400`
Channel 1	RPU 0	0	`0xff99'0000`
Channel 2	RPU 1	1	`0xff99'0200`
Channel 3	PMU	7	`0xff99'0e00`
Channel 4	PMU	7
Channel 5	PMU	7
Channel 6	PMU	7
Channel 7	PL 0	3	`0xff99'0600`
Channel 8	PL 1	4	`0xff99'0800`
Channel 9	PL 2	5	`0xff99'0a00`
Channel 10	PL 3	6	`0xff99'0c00`

0x200 byte の領域の区切られ方も buffer index 順です。ということで RPU 0 (ch 1, idx 0) -> APU (ch 7, idx 3) の IPI では 0xff99'00c0 と 0xff99'00e0、APU -> RPU 0 の IPI では 0xff99'0600 と 0xff99'0620 を使えばいいことがわかります。Linux の場合は Devicetree にこんな感じの設定をし、IPI レジスタと同様 mmap した領域を介してアクセスできるようにしました。なお、実際に Message Buffer を使っているのは APU から RPU に IPI するときだけです。

/ {
  ipi-buffer@ff990000 {
    compatible = "generic-uio";
    reg = <0x0 0xff990600 0x0 0x20>, // APU -> RPU0 request
          <0x0 0xff990620 0x0 0x20>, // RPU0 -> APU response
          <0x0 0xff9900c0 0x0 0x20>, // RPU0 -> APU request
          <0x0 0xff9900e0 0x0 0x20>; // APU -> RPU0 response
  };
};

L チカを支える TTC

RPU から使えるタイマー・カウンターとして、LPD にある4つの Triple-timer counter (TTC) があります。今回はこのうちの1つを 10 Hz で割り込みが飛ぶようにして L チカのタイミング制御に使っています。

TTC は名前の通り、3つのカウンターを持つユニットです。それが4つあるので合計12個のカウンターがあることになります。xparameters.h では、1つ目の TTC が持つカウンターから順に XPAR_PSU_TTC_0_*, XPAR_PSU_TTC_1_*, …, XPAR_PSU_TTC_12_* と名前が付いています。ちょっとまぎらわしいので注意です。また XSCT で BSP を作ったときに出力されるメッセージや xparameters.h の記述にある通り、カウンターの1つは sleep などの実装に使われるようなので、実際に使えるカウンターは11個です。

+generate-src | psu_ttc_3 will be used in sleep routines for delay generation

今回は xparameters.h の XPAR_PSU_TTC_0、つまり TTC0 の1つ目のカウンターを使いました。10 Hz の Interval Mode で割り込みを設定するならこんな感じです。ちなみに、デバッグなどで実行中のアプリケーションを何度もロードし直すことも想定した場合、XTtcPs_CfgInitialize() の前にレジスタを直接操作するなどで TTC を無理やり無効化するなどの処理を入れるのがいいと思います。もしこのタイミングで TTC が動いていた場合、XTtcPs_CfgInitialize() がエラーを返してしまうためです。

static void ttc_irq_handler(void* data) noexcept {
  auto ttc = static_cast<XTtcPs*>(data);
  const auto status = XTtcPs_GetInterruptStatus(ttc);
  if (status & XTTCPS_IXR_INTERVAL_MASK) {
    // ...

    XTtcPs_ClearInterruptStatus(ttc, XTTCPS_IXR_INTERVAL_MASK);
  }
}


XTtcPs ttc{};
{
  auto cfg = XTtcPs_LookupConfig(XPAR_PSU_TTC_0_DEVICE_ID);
  XTtcPs_CfgInitialize(&ttc, cfg, cfg->BaseAddress);

  XTtcPs_SetOptions(&ttc, XTTCPS_OPTION_INTERVAL_MODE | XTTCPS_OPTION_WAVE_DISABLE);

  XInterval interval;
  std::uint8_t prescaler;
  XTtcPs_CalcIntervalFromFreq(&ttc, 10, &interval, &prescaler); // 10 Hz
  XTtcPs_SetInterval(&ttc, interval);
  XTtcPs_SetPrescaler(&ttc, prescaler);

  XTtcPs_EnableInterrupts(&ttc, XTTCPS_IXR_INTERVAL_MASK);
  XTtcPs_ClearInterruptStatus(&ttc, XTTCPS_IXR_ALL_MASK);

  XScuGic_Connect(&gic, XPAR_PSU_TTC_0_INTR, ttc_irq_handler, &ttc);
  XScuGic_Enable(&gic, XPAR_PSU_TTC_0_INTR);
}

PS GPIO の任意の複数ピンを同時に扱う

ほかに RPU から使っているのは GPIO です。Ultra96 の LED は PS_MIO{17, ..., 20} につながっているので XGpioPs を使います。

GPIO の操作というと、ピン単位かポートやバンクなどと呼ばれるまとまった単位で操作するのが一般的だと思います。XGpioPs も、XGpioPs_Read(), XGpioPs_Write() などバンク単位での操作と、XGpioPs_ReadPin(), XGpioPs_WritePin() などピン単位の操作が C の関数として定義されています。LED 4つを一度に操作するなら、ちょうどそれらが同じバンクにあるので、例えばこんな感じにかけそうです。

inline constexpr std::uint32_t GPIO_BANK0_LED_MASK = std::uint32_t{0b1111} << 17;

inline void set_ultra96_leds(XGpioPs& gpio, std::uint8_t value) noexcept {
  const auto r = XGpioPs_Read(&gpio, 0);
  XGpioPs_Write(&gpio, 0, (r & ~GPIO_BANK0_LED_MASK) | ((value * 0b1111) << 17));
}

しかし、これだと一度 GPIO の値を読み出しているのがなんだかもにょっとします。また、XGpioPs_Write() がそのバンク全体に影響する操作なのもちょっとこわいです。特に APU で動いている Linux も GPIO を触れる状況にあるので、(実際に bank 0 を使うものはいないはずですが) 互いの処理の実行され方によっては整合性が取れなくなってしまうかもしれません。もちろん、そんな状況が想定される設計にしないに越したことはありませんが、いずれにせよ Zynq という同じメモリ空間を複数のプロセッサなどが共有している環境では注意しておくべきです⁸。

どうしたものかと TRM などを眺めていると、MASK_DATA_{LSW,MSW} というレジスタがあるのに気づきます。これは各バンクに属する下 16 bit・上 10 bit に対し、一度にビットマスクとデータを渡すことで特定のピンだけの出力を指定できるようです。まさに探していたものですね。PS_MIO{17, ..., 20} は bank 0 の上位10 bit の枠になるので、MASK_DATA_0_MSW に対してこんな感じにしてやればいいですね。

inline constexpr std::uint32_t GPIO_BANK0_LED_MASK = std::uint32_t{0b1111} << 17;

inline void set_ultra96_leds(XGpioPs& gpio, std::uint8_t value) noexcept {
  XGpioPs_WriteReg(
    gpio.GpioConfig.BaseAddr, XGPIOPS_DATA_MSW_OFFSET,
    // MASK_DATA_0_MSW の上位 16 bit はマスク
    // `PS_MIO{17, ..., 20}` 以外に対応するものを 1 にする
    (~GPIO_BANK0_LED_MASK & 0xffff0000) |
    // `PS_MIO{17, ..., 20}` に設定する値
    ((value & 0b1111) << 1)
  );
}

Vitis で作ったベアメタルアプリケーションを CMake でビルドする

上でちょろっと紹介したように、RPU 側アプリケーションの実装は Vitis で作った Appication Project からファイルを持ってきた上で CMake でビルドできるようにしたものです。main.cc 1つだけにわざわざ CMake を使わなくてよいですが、これをテンプレート的に別プロジェクトで使いまわすことを想定してのものです。

embeddedsw で提供されるいろいろを使うには、libxil.a などをリンクしなければいけません。libxil.a の検出とコンパイル・リンクのために、少々雑ではありますが FindLibXil.cmake を書きました。standalone 以外のライブラリも find_package() の COMPONENTS で指定できるようになっています。各ライブラリに対応するターゲットは、add_library(LibXil::standalone INTERFACE IMPORTED) のように INTERFACE IMPORTED で宣言しています。よくある STATIC や UNKNOWN でなく INTERFACE なのは、これらを単に -l<ほげほげ> でリンクできず、--start-group,...,--end-group でリンク順を明示してやらないといけないためです。続く set_target_properties() でそうしたリンクオプションを指定しています。

if(LibXil_standalone_FOUND AND NOT TARGET LibXil::standalone)
  add_library(LibXil::standalone INTERFACE IMPORTED)
  set_target_properties(LibXil::standalone PROPERTIES
    INTERFACE_LINK_LIBRARIES "-Wl,--start-group,${standalone_lib},-lgcc,-lc,-lstdc++,--end-group"
    INTERFACE_INCLUDE_DIRECTORIES "${standalone_include}")
endif()

ちなみに、各ライブラリをどの順でリンクすればいいのかは、embeddedsw の .mld ファイルで OPTION APP_LINKER_FLAGS を見ればよいです。例えば xilffs ならこんな行があるのを見つけられると思います。

OPTION APP_LINKER_FLAGS = "-Wl,--start-group,-lxilffs,-lxil,-lgcc,-lc,--end-group";

ISR で atomic 使うのって実際どうなの

割り込みハンドラーにたくさん実装を入れたくないので、「割り込みがあったかどうかのフラグ」を立てるなど最低限の処理だけにして、実際の処理はメインループの中でやる、という実装をしています。こうした「割り込みがあったかどうかのフラグ」などの割り込みハンドラーと共有する値は、コンパイラが意図しない最適化をしてしまわないように何かしらの対策をするのが一般的です。その値がコンパイラから見てどこか別のところから書き換えられることのない定数のように見えたとしても、実際には突発的に呼び出される割り込みハンドラーから書き換えられる可能性がるからコードの意味を変えないでね、と伝えてやるイメージです。

C/C++ の組み込みプログラミングでよく使われるのが volatile です。ただ volatile が何者なのか正直よくわからず、なんだか「とりあえず volatile 付けておけば安心！」に見えてしまうのでうーんです。その代替手段として <atomic> を試してみています。

一番単純な例が TTC 割り込みの部分です。std::atomic_flag を使い、set を割り込み待ちの状態、clear を割り込みが起きた状態とします。メインループの中で test_and_set() を呼び出し、その時点での値が clear された状態 (false) だったら割り込みに対する処理、という感じです。

static std::atomic_flag ttc_irq_kicked_n = ATOMIC_FLAG_INIT;

static void ttc_irq_handler(void* data) noexcept {
  auto ttc = static_cast<XTtcPs*>(data);
  const auto status = XTtcPs_GetInterruptStatus(ttc);
  if (status & XTTCPS_IXR_INTERVAL_MASK) {
    ttc_irq_kicked_n.clear(std::memory_order_relaxed);

    XTtcPs_ClearInterruptStatus(ttc, XTTCPS_IXR_INTERVAL_MASK);
  }
}

for (;;) {
  asm volatile("wfi");

  if (!ttc_irq_kicked_n.test_and_set(std::memory_order_relaxed)) {
    // TTC 割り込みがあったときの処理
  }
}

IPI 割り込みでは std::atomic<std::uint32_t> を使って Message Buffer から読み込んだ値を渡す目的も兼ねています。最上位ビットを割り込みが起きた状態かどうかに、残りを Message Buffer から呼んだ値とします。メインループでは exchange() を呼び出して値を 0 に置き換えつつ、その時点での値の最上位ビットが立っていたら割り込みに対する処理、という感じです。

static std::atomic<std::uint32_t> ipi_req{0};

static void ipi_irq_handler(void* data) noexcept {
  auto ipi = static_cast<XIpiPsu*>(data);
  const auto status = XIpiPsu_GetInterruptStatus(ipi);
  if (status & IPI_TRIG_CH7_MASK) {
    const std::uint32_t req = Xil_In32(XPAR_PSU_MESSAGE_BUFFERS_S_AXI_BASEADDR + 0x600);
    ipi_req.store(req | 0x8000'0000, std::memory_order_relaxed);

    XIpiPsu_ClearInterruptStatus(ipi, IPI_TRIG_CH7_MASK);
  }
}

for (;;) {
  asm volatile("wfi");

  if (const auto req = ipi_req.exchange(0, std::memory_order_relaxed); req & 0x8000'0000) {
    // TTC 割り込みがあったときの処理
  }
}

これでどちらもそれっぽく動いているものの、正直 volatile と同様に <atomic> についても詳しいわけではないので、この使い方がアリなのかあまり自信がありません。Rust のこの資料とかは一例として紹介されたりはしていますね。

RPU の Lock-Step Mode と TCM

RPU は Tightly Coupled Memory (TCM) とよばれる特別なメモリ領域にプログラムを配置できます。TCM はキャッシュを介さない予測可能時間でのアクセスや ECC が付いていたりする、RPU らしいメモリです。しかしこの TCM、容量がコア毎に 64 KB x 2 なので、ちょっと大きなものを載せようとすると厳しいことがあります。実際、開発中に .text が 64 KB を超えて収まらなくなったことがありました。

この対策 (?) になりそうな方法の1つとして、RPU を Lock-Step で動かすというのがあります。TRM によれば

During the lock-step operation, the TCMs that are associated with the redundant processor become available to the lock-step processor. The size of ATCM and BTCM become 128 KB each with BTCM supporting interleaved accesses from processor and AXI slave interface.

とあるためです。で、実際に linker script を変えてみたのですが…なんだかあやしいです。デバッガーでロードさせると問題ないのに、boot.bin に入れて FSBL で Linux と一緒にロードさせると途中で RPU 側のアプリケーションがお亡くなりになってしまうのです。デバッガーを使うと問題ないというのが厄介で、結局調査は諦めました。.text が 64 KB 超えた問題も、ちょっとコード変えただけで余裕で収まるようになりましたし。しかし謎…。

Systemd Unit File を追加して Ubuntu のブート時にいろいろ動かす

Linux 側で動かすアプリケーションは、電源を投入したら何もせず勝手に動いてほしいです。今回は Ubuntu が動いているので、そこに Systemd の unit file を追加して実現しました。こんな感じです。

[Unit]
Description=Trigger IPI to flash LEDs
Wants=modprobe@uio_pdrv_genirq.service
After=modprobe@uio_pdrv_genirq.service

[Service]
Type=simple
ExecStart=/usr/bin/ipi-led
DevicePolicy=closed
DeviceAllow=char-uio

[Install]
WantedBy=multi-user.target

Systemd 世代なら見慣れた記述だと思います。カーネルモジュール uio_pdrv_genirq に依存しているので、それを modprobe@uio_pdrv_genirq.service と指定しています。[Service] で指定した処理は特に何もしなければ root で動いてしまうので、本格的に何かやろうとするなら別ユーザーで動かすなど権限を絞るべきです。今回は一発ネタなので手を抜いています。とはいえ何もしないのもおもしろくないので、お気持ち程度のリソース制限を付けました。DevicePolicy=closed と DeviceAllow=char-uio を設定して、ipi-led からは /dev/null, /dev/zero などの基本的なデバイスと /dev/uio* しか見えなくなっているはずです。

ipi-led 以外にもいくつかの unit file を追加しています。まずは maximize-root-partition.service です。disk.img.zst で作った Linux 側のパーティションは 256 MiB しかないので、最初にブートしたときに parted と resize2fs を呼び出してリサイズします。リサイズが済んだらもう役目はないので、unit file の中で systemctl disable しています。

もう1つが setup-usb-ether.service で、USB Gadget を使ったネットワーク接続を設定します。USB Gadget 経由のネットワークは想像していたより快適でした。Ultra96 実機上で複雑な作業をするのであればぜひオススメしたいです。ちなみに、これに関連して system-top-append.dts に PS-GTR の refclock の設定や USB 関連の pinctrl の設定を追加しています。設定しないとないと相手 PC 側で突然 disconnect 扱いになってしまうなど不安定でした。PS-GTR の refclock 情報は .xsa に入っていた気がするので、それだけでもやってくれるといいのになと思いました。

naruhodo pic.twitter.com/iapfw9ABxP
— ✧*。ヾ(｡ᐳ﹏ᐸ｡)ﾉﾞ。*✧ (@myon___) April 24, 2022

せっかくなので、USB で繋いだらすぐ SSH できるようにと Ubuntu 環境に openssh-server も入れようとしていました。ただ、Ubuntu の openssh パッケージはパッケージがインストールされるときに host key を生成しているようだったため見送りました⁹。こうしたファイルを配布も想定したディスクイメージに含めたくないし、かと言って何かしらの workaround を設定するのも面倒だったので。

もっと言えば、インターネットから拾ってきた実行ファイルをむやみに実行したくないのでソースコードからビルドしています。Earthly の最新機能を追うきっかけにもなりますしね。 ↩
BSP とかの Makefile を見ると -j10 がハードコーディングされていたり、一方でどう見てもターゲットの依存関係や並列ビルドであやしくなりそうな箇所がありますよね…。Earthly が持つ、ある条件での処理をコンテナ内で1度だけ実行するという特徴は、こういったヤツらのトラブルを避けるのにも有効です。 ↩
何も意識せずに tar.xz を指定して、やけに時間かかるなーってなる出来事がありました… ↩
FSBL の psu_init() 前に実行されてしまうから…？ ↩
あるいはキャッシュを意図的に消すか GC がかからない限り。 ↩
パッケージマネージャなど、何かをダウンロードする系とは相性がよさそうです。一方でビルドキャッシュに使うのは注意な気がします、特に C や C++ を使っている場合。 ↩
APU にデフォルトで割り当てられているのは channel 0 です。ただしこれは、XSCT が生成した Devicetree ノード mailbox@ff990400 や OpenAMP 関連の資料にあるように PMU とやりとりするのに使っているようです。RPU 0 とやりとりで扱うビットに影響しない気もしますが、わざわざほかのプロセッサやソフトウェアが既に使っている領域を共有する必要もないです。channel 7 以降は未割り当てなのでこれを使います。 ↩
SoC 内のあらゆるリソースが同じメモリ空間にアクセスできるの、Zynq のおもしろく強力であり、同時にコワイところですよね。ちなみに XSCT が生成する .dts はデフォルトで何でも有効になっているので、RPU などからさわるリソースは status を disabled または reserved にしたり、PL 上のリソースは /delete-node/ するのがよいです。デバイスドライバーによっては probe の段階でペリフェラルにリセットかけたりとかしちゃうので。 ↩
これに限らず、Ubuntu とかのパッケージはインストール時の hook でいろいろやり過ぎな気がします。特にパッケージに含まれるサービスをその場で start してくるやつが本当に好きじゃないです。ソフトウェアの設定を確認する前に勝手に動き出しちゃうってこわくないですか。 ↩