Raspberry Pi 5はCPUコアがCortex-A76に変わり、I/OがRP1サウスブリッジに分離された。Yoctoで扱う場合、RPi4の知識だけでは足りない部分がある。
この記事では、Yocto Scarthgap 5.0 LTSでRaspberry Pi 5のヘッドレスイメージをビルドし、Wi-Fiで接続できるところまでを実践する。U-Bootの問題やWi-Fiドライバの既知の問題も含めて、ハマりどころを先に押さえておこう。
RPi5のアーキテクチャ変更点
RPi5はRPi4から大きくアーキテクチャが変わった。Yoctoビルドに影響するポイントを整理する。
| 項目 | RPi 4（BCM2711） | RPi 5（BCM2712） |
|---|---|---|
| CPUコア | Cortex-A72 @ 1.8 GHz | Cortex-A76 @ 2.4 GHz |
| プロセス | 28nm | 16nm |
| GPU | VideoCore VI | VideoCore VII |
| I/Oアーキテクチャ | SoC統合 | RP1サウスブリッジ（PCIe x4接続） |
| PCIe | なし | PCIe 2.0 x1（FPCコネクタ） |
| USB 3.0 | 帯域共有 | ポートごとに5 Gbps |
| 電源 | 5V/3A | 5V/5A（USB-PD） |
最大の変更はRP1サウスブリッジ だ。RPi4ではEthernet・USB・GPIOがSoCに統合されていたが、RPi5ではこれらがRP1チップに分離され、PCIe x4でSoCと接続されている。このため、デバイスツリーやドライバの構成がRPi4とは異なる。RPi3/4の場合はRPiビルドガイドを参照してほしい。
ビルド環境の構築
ホストの準備
Ubuntu 24.04 LTSを推奨。必要パッケージをインストールする。
sudo apt update
sudo apt install -y gawk wget git diffstat unzip texinfo gcc build-essential \
chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool \
file locales libacl1
sudo locale-gen en_US.UTF-8
Poky + メタレイヤーのクローン
mkdir -p ~/yocto && cd ~/yocto
git clone -b scarthgap git://git.yoctoproject.org/poky
git clone -b scarthgap git://git.openembedded.org/meta-openembedded
git clone -b scarthgap git://git.yoctoproject.org/meta-raspberrypi
git clone -b scarthgap/u-boot https://git.yoctoproject.org/meta-lts-mixins
meta-raspberrypi は scarthgap ブランチを使う。meta-lts-mixins は scarthgap/u-boot ブランチだ。この理由は次のセクションで説明する。
bblayers.confの設定
source poky/oe-init-build-env build-rpi5
conf/bblayers.conf にレイヤーを追加する。
# conf/bblayers.conf
BBLAYERS ?= " \
/home/user/yocto/poky/meta \
/home/user/yocto/poky/meta-poky \
/home/user/yocto/poky/meta-yocto-bsp \
/home/user/yocto/meta-openembedded/meta-oe \
/home/user/yocto/meta-openembedded/meta-python \
/home/user/yocto/meta-openembedded/meta-networking \
/home/user/yocto/meta-raspberrypi \
/home/user/yocto/meta-lts-mixins \
"
U-Boot問題と対策
なぜmeta-lts-mixinsが必要か
Scarthgapが標準で使うU-Bootは v2024.01 だ。しかし、RPi5のサポートはU-Boot v2024.04 で初めて追加された。つまり、デフォルトのScarthgapではRPi5でU-Bootが動作しない。
meta-lts-mixins（scarthgap/u-boot ブランチ）は、U-Boot v2024.04をScarthgapにバックポートするレイヤーだ。これを追加することで、RPi5でU-Bootが正常に起動する。
U-Bootを使わない選択肢
U-Bootを使わず、RPi5のファームウェアから直接カーネルを起動することもできる。ただし、U-Bootを使う方がネットワークブートやA/Bパーティション切り替えなどの柔軟性がある。特別な理由がなければ、meta-lts-mixins を追加してU-Bootを使う構成を推奨する。
ビルド設定
基本設定
# conf/local.conf
MACHINE = "raspberrypi5"
# sstate-cacheとダウンロードを外部に配置
SSTATE_DIR = "/home/user/yocto/sstate-cache"
DL_DIR = "/home/user/yocto/downloads"
sstate-cacheの外部配置についてはビルド高速化ガイドで詳しく解説している。
systemd有効化
ヘッドレス運用では、systemdをinitマネージャとして使う。
# conf/local.conf
DISTRO_FEATURES:append = " systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED:append = " sysvinit"
VIRTUAL-RUNTIME_init_manager = "systemd"
VIRTUAL-RUNTIME_initscripts = "systemd-compat-units"
systemdサービスの作成方法はsystemdサービスガイドにまとめている。
Wi-Fi対応設定
RPi5のWi-Fiを動作させるには、カーネルモジュールとファームウェアの明示的な追加が必要だ。
# conf/local.conf — Wi-Fi有効化
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac-wcc"
IMAGE_INSTALL:append = " wireless-regdb-static"
IMAGE_INSTALL:append = " wpa-supplicant"
brcmfmac-wcc はBroadcom Wi-Fiドライバの依存モジュールで、これがないとWi-Fiインターフェースが認識されない。wireless-regdb-static は無線LANの国別規制データベースだ。
wpa_supplicant設定ファイルの組み込み
Wi-Fiの接続情報をビルド時にイメージに焼き込む。bbappendを使ってwpa_supplicantの設定ファイルを追加する。
# meta-mylayer/recipes-connectivity/wpa-supplicant/wpa-supplicant_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://wpa_supplicant-wlan0.conf"
do_install:append() {
install -d ${D}${sysconfdir}/wpa_supplicant/
install -m 0600 ${WORKDIR}/wpa_supplicant-wlan0.conf \
${D}${sysconfdir}/wpa_supplicant/wpa_supplicant-wlan0.conf
}
# meta-mylayer/recipes-connectivity/wpa-supplicant/files/wpa_supplicant-wlan0.conf
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
country=JP
network={
ssid="YOUR_SSID"
psk="YOUR_PASSWORD"
key_mgmt=WPA-PSK
}
systemd-networkdでWi-Fiインターフェースを有効化
# meta-mylayer/recipes-core/systemd/systemd_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://wlan0.network"
do_install:append() {
install -d ${D}${sysconfdir}/systemd/network/
install -m 0644 ${WORKDIR}/wlan0.network \
${D}${sysconfdir}/systemd/network/wlan0.network
}
# meta-mylayer/recipes-core/systemd/files/wlan0.network
[Match]
Name=wlan0
[Network]
DHCP=ipv4
wpa_supplicantサービスの自動起動
# meta-mylayer/recipes-connectivity/wpa-supplicant/wpa-supplicant_%.bbappend（上記に追記）
SYSTEMD_AUTO_ENABLE:${PN} = "enable"
systemd-networkdとwpa_supplicantの連携により、起動時に自動でWi-Fiに接続する。
ビルドと書き込み
ビルド実行
bitbake core-image-base
初回ビルドはハードウェア次第で数時間かかる。ビルド高速化のテクニックを事前に設定しておくと待ち時間を大幅に短縮できる。
SDカードへの書き込み
cd tmp/deploy/images/raspberrypi5/
# bmaptoolを使う場合（推奨）
sudo bmaptool copy core-image-base-raspberrypi5.wic.bz2 /dev/sdX
# ddを使う場合
bzcat core-image-base-raspberrypi5.wic.bz2 | sudo dd of=/dev/sdX bs=4M status=progress
sync
動作確認
SDカードをRPi5に挿入して起動。シリアルコンソール（UART）またはHDMIで接続する。
# Wi-Fiの確認
ip addr show wlan0
ping -c 3 8.8.8.8
wlan0 にIPアドレスが割り当てられていれば成功だ。
既知の問題と対処法
Wi-Fiインターフェースが認識されない
症状: ip link に wlan0 が表示されない。
原因: brcmfmac-wcc モジュールが不足している。
対処: conf/local.conf に以下を追加。
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-brcmfmac-wcc"
IMAGE_INSTALL:append = " wireless-regdb-static"
vc4graphics + meta-networking の起動障害
症状: meta-networking レイヤーを追加するとRPi5が起動しなくなる。
原因: vc4graphics MACHINE_FEATURE と meta-networking の組み合わせで既知の問題がある（meta-raspberrypi issue #1383）。
対処: vc4graphics が不要なヘッドレス構成なら、MACHINE_FEATURESから除外する。
# conf/local.conf
MACHINE_FEATURES:remove = "vc4graphics"
U-Boot USBの問題
症状: U-BootのUSB Mass Storage（UMS）機能が動作しない。
原因: meta-raspberrypi issue #1464。U-Bootのデバイスツリーの問題。
対処: 通常のブートには影響しない。UMS機能が必要な場合は、issueの進捗を確認すること。
まとめ
RPi5 × Yocto Scarthgapでヘッドレスイメージをビルドする手順を整理した。
| ステップ | ポイント |
|---|---|
| レイヤー準備 | meta-lts-mixins（scarthgap/u-boot）を忘れない |
| MACHINE設定 | raspberrypi5 |
| Wi-Fi有効化 | brcmfmac + brcmfmac-wcc + wireless-regdb-static |
| ネットワーク | systemd-networkd + wpa_supplicant |
| 書き込み | bmaptoolまたはdd |
RPi5はRP1サウスブリッジの導入でRPi4とは異なるデバイスツリー構成になっている。しかし、meta-raspberrypi と meta-lts-mixins が対応を吸収してくれるため、ユーザーが気にすべきことは限定的だ。
既知の問題（Wi-Fiドライバ、vc4graphics）はワークアラウンドで対処できる。meta-raspberrypiのissueを定期的に確認し、修正が入ったらワークアラウンドを外そう。