meta-raspberrypi machine配置深度解析rpi-base.inc与50设备树overlay选择完整指南【免费下载链接】meta-raspberrypiYocto/OE BSP layer for the Raspberry Pi boards项目地址: https://gitcode.com/gh_mirrors/me/meta-raspberrypimeta-raspberrypi 是面向 Raspberry Pi树莓派全家族的 Yocto Project / OE BSP 层它通过一套machine 配置继承体系和设备树 overlay 清单让你为 Pi 1 到 Pi 5 生成可直接烧录的 SD 卡镜像。本文带你读懂核心文件rpi-base.inc掌握 50 个 dtbo overlay 的选择技巧。 项目概览meta-raspberrypi 能做什么这个 layer 覆盖了你 Yocto 构建树莓派系统所需的全部硬件适配工作17 个 machine 配置从经典 Pi B 到最新的 Pi 532/64 位各有对应设备树打包70 个 overlay.dtbo与基础.dtb自动写入 SD 卡启动分区固件与启动文件bootloader、armstub、WiFi/蓝牙固件bcm43xx 系列图形栈选择自动在 VC4 KMS mesa 与 legacy userland 之间切换所有 machine 配置集中在conf/machine/目录每个.conf文件对应一块板子例如conf/machine/raspberrypi4.conf32 位 Pi 4与conf/machine/raspberrypi5.conf64 位 Pi 5。️ machine 配置的三层继承结构每个 board 的.conf文件都非常简短因为它们只负责两件事指定 CPU tune和包含公共配置。以conf/machine/raspberrypi4.conf为例第一行声明DEFAULTTUNE如cortexa7thf-neon-vfpv4require对应的 CPU tune 文件如arm/armv7a/tune-cortexa7.incinclude conf/machine/include/rpi-base.inc引入全部公共逻辑而conf/machine/include/rpi-base.inc又会进一步引入三个配套文件文件职责rpi-default-settings.inc默认行为SD 卡镜像类型、测试套件替换rpi-default-versions.inc内核版本偏好64 位默认 6.1832 位 6.12rpi-default-providers.inc图形库 provider 切换vc4graphics 特征存在时用 mesa否则用 userland这套薄 board 配置 厚公共 include的结构是理解整个 layer 的钥匙改公共行为改 include改单板差异改 .conf。 rpi-base.inc 精读8 个关键变量rpi-base.inc约 190 行核心逻辑可以归纳为以下几块内核镜像格式自动选择KERNEL_IMAGETYPEPi 的固件支持两种加载方式rpi-base.inc 根据RPI_USE_U_BOOT自动切换不用 u-boot32 位用zImage、64 位用Image由 Pi 固件直接加载启用 u-boot32 位用uImagebootm命令Pi 5 / armv8 则统一用Imagebooti所以你会看到raspberrypi5.conf里明确写了KERNEL_BOOTCMD booti而老 Pi 默认是bootm。设备树清单KERNEL_DEVICETREE变量分两段拼接RPI_KERNEL_DEVICETREE16 个基础.dtbbcm2708 → bcm2712 各代 SoCRPI_KERNEL_DEVICETREE_OVERLAYS70 个.dtbooverlay前面列出的就是这里各 board 的.conf可以用RPI_KERNEL_DEVICETREE ...覆盖基础清单。例如raspberrypi5.conf只保留 5 个 bcm2712 系列的 dtb而多板兼容机raspberrypi-armv8.conf则罗列了 Pi 2B 到 Pi 5 的全部 dtb。条件式依赖注入rpi-base.inc 通过oe.utils.conditional实现按需打包ENABLE_I2C 1 → 打包 i2c-dev / i2c-bcm2708 内核模块 ENABLE_IR 1 → 打包 gpio-ir 模块 对应 overlay ENABLE_GPIO_SHUTDOWN 1 → 打包 gpio-shutdown gpio-keys 模块这些开关在docs/extra-build-config.md中有完整说明配合ENABLE_CAN、ENABLE_W1等变量可以让同一份 layer 适配 CAN 总线、红外遥控、温度传感器等外设。启动分区的组装器make_dtb_boot_files这是 rpi-base.inc 中最巧妙的一个 Python 函数它遍历KERNEL_DEVICETREE为每个条目生成IMAGE_BOOT_FILES项并约定.dtbo与两个 map 文件要放到 SD 卡overlays/子目录基础.dtb放在根目录。之后classes/sdcard_image-rpi.bbclass里的IMAGE_CMD:rpi_sdimg会用mcopy把它们逐一拷入 FAT32 启动分区。 70 设备树 overlay 都装了什么打开rpi-base.inc中的RPI_KERNEL_DEVICETREE_OVERLAYS可以按用途分组记忆分类代表 overlay用途 音频hifiberry-dacplusadc、iqaudio-dac、wm8960-soundcardHiFiBerry / iQAudio 声卡 摄像头imx219、imx477、imx708相机模块 V2 / V3 传感器️ 显示vc4-kms-v3d(-pi4/-pi5)、pitft22/28/35KMS 显示与 PiTFT 屏 通信mcp2515-can0/can1、uart0~uart5含 pi5 变体CAN 总线、串口重映射️ GPIOgpio-shutdown、w1-gpio、gpio-key、dwc2关机按键、1-Wire、USB OTG 开关disable-bt(-pi5)、disable-wifi(-pi5)、rpi-poe禁用内置 BT/WiFi、PoE️ 映射overlay_map.dtb、hat_map.dtb让dtoverlay按名字解析注意uart 类 overlay 在 Pi 5 上有-pi5变体如uart0-pi5.dtbow1-gpio 同样如此——选 overlay 前先看你的板子代际。 设备树 overlay 选择技巧6 个常见场景overlay 打包进镜像 ≠ 自动生效。生效要靠启动分区的config.txt写一行dtoverlayxxx。meta-raspberrypi 提供了三种方式1. 用变量一键启用推荐在local.conf里设变量layer 会自动把对应 overlay 写进 config.txt 并打包所需内核模块ENABLE_CAN 1 # → dtoverlaymcp2515-can0 ENABLE_W1 1 # → dtoverlayw1-gpio ENABLE_IR 1 # → dtoverlaygpio-ir gpio-ir-tx2. 用 RPI_EXTRA_CONFIG 手动追加docs/extra-build-config.md中说明任何没有专用变量的选项都可以用RPI_EXTRA_CONFIG向 config.txt 追加任意行多行用\n分隔RPI_EXTRA_CONFIG \ndtoverlayimx219\n3. 显示模式的特殊变量 VC4DTBOKMS 显示由VC4DTBO控制各 machine 的默认值已写好Pi 5raspberrypi5.confvc4-kms-v3dPi 4 32 位vc4-kms-v3d通用 armv8vc4-fkms-v3d不想要 KMS 显示栈设DISABLE_VC4GRAPHICS 1machine 会摘掉vc4graphics特征图形 provider 自动切回 userland4. 多板镜像时 overlay 如何取舍如果目标覆盖多种板子raspberrypi-armv7/raspberrypi-armv8两个多板 machine默认 overlay 全集都会进镜像体积换兼容性单板 machine 则只带本板 dtb镜像更小、启动分区更干净——生产环境建议选单板 machine。5. 相机 overlay 与 CMA启用 imx219 / imx708 相机 overlay 时文档还提醒需在 config.txt 中设置cma相关参数docs/extra-build-config.md第 416 行起的 Enable Raspberry Pi Camera Module 一节有详细说明。6. 验证生效烧卡启动后在/proc/device-tree/或dmesg | grep -i dtbo中能看到已加载的 overlay 名称/boot/overlays/下应有你选用的.dtbo文件。 17 个 machine 配置速查表MACHINE板卡内核文件名SDIMG_KERNELIMAGE内核版本raspberrypiPi Barm1176kernel.img6.12raspberrypi0/-0-wifi/-0-2wPi Zero 系列kernel7(2) 系列6.12raspberrypi2/raspberrypi2-64Pi 2kernel7l.img / kernel8.img6.12 / 6.18raspberrypi3/raspberrypi3-64Pi 3 全系kernel7l.img / kernel8.img6.12 / 6.18raspberrypi4/raspberrypi4-64Pi 4 / 400kernel7l.img / kernel8.img6.12 / 6.18raspberrypi5Pi 5 / CM5kernel_2712.img6.18raspberrypi-cm/-cm3/-cm5-io-board计算模块随对应板—raspberrypi-armv7/raspberrypi-armv8多板兼容机多文件名见 include两个实用细节64 位 Pi 5 的串口是ttyAMA10其他板多为ttyS0或ttyAMA0远程调试时别配错Pi 4 32 位被锁定在 6.12 内核raspberrypi4.conf注释说明 6.18 已移除 Pi 4 的 32 位配置 新手避坑清单找不到启动文件先确认BOOTFILES_DIR_NAME默认bootfiles目录内容是否被rpi-bootfilesrecipe 正确部署EXTRA_IMAGEDEPENDS已自动加上它镜像里为何没有内核rpi-base.inc 末尾RDEPENDS:${KERNEL_PACKAGE_NAME}-base 是故意的——内核在 FAT32 分区rootfs 不重复携带overlay 改了不生效检查 config.txt 拼写dtoverlay靠overlay_map.dtb/hat_map.dtb解析名字两个 map 文件必须存在WiFi 没固件基础linux-firmware不含 RPi 无线固件需 layer 内linux-firmware-rpidistro提供各 machine 已通过MACHINE_EXTRA_RRECOMMENDS自动带上 bcm43xx 固件包想改默认内核版本改conf/machine/include/rpi-default-versions.inc里的PREFERRED_VERSION_linux-raspberrypi或在单个 machine 中覆盖如 Pi 4 32 位锁 6.12 就是这么做的 关键文件路径速查路径说明conf/machine/include/rpi-base.inc本文主角公共 machine 逻辑conf/machine/include/rpi-default-*.inc设置 / 版本 / provider 三件套conf/machine/raspberrypi*.conf17 个板级 machine 配置classes/sdcard_image-rpi.bbclassSD 卡镜像分区组装逻辑files/wic/sdimage-raspberrypi.wksWIC 布局描述文件docs/extra-build-config.mdconfig.txt 高级配置与 overlay 开关docs/layer-contents.md支持的 machine 与镜像清单掌握rpi-base.inc的继承链和 overlay 清单后你已能独立完成单板最小镜像构建 → 按外设追加 overlay → 生成可烧录 SD 卡镜像 的完整闭环。下一步建议从rpi-test-image跑通全流程再按docs/extra-build-config.md逐项开启你的外设。【免费下载链接】meta-raspberrypiYocto/OE BSP layer for the Raspberry Pi boards项目地址: https://gitcode.com/gh_mirrors/me/meta-raspberrypi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 meta-raspberrypi machine配置深度解析：rpi-base.inc与50+设备树overlay选择完整指南
meta-raspberrypi machine配置深度解析rpi-base.inc与50设备树overlay选择完整指南【免费下载链接】meta-raspberrypiYocto/OE BSP layer for the Raspberry Pi boards项目地址: https://gitcode.com/gh_mirrors/me/meta-raspberrypimeta-raspberrypi 是面向 Raspberry Pi树莓派全家族的 Yocto Project / OE BSP 层它通过一套machine 配置继承体系和设备树 overlay 清单让你为 Pi 1 到 Pi 5 生成可直接烧录的 SD 卡镜像。本文带你读懂核心文件rpi-base.inc掌握 50 个 dtbo overlay 的选择技巧。 项目概览meta-raspberrypi 能做什么这个 layer 覆盖了你 Yocto 构建树莓派系统所需的全部硬件适配工作17 个 machine 配置从经典 Pi B 到最新的 Pi 532/64 位各有对应设备树打包70 个 overlay.dtbo与基础.dtb自动写入 SD 卡启动分区固件与启动文件bootloader、armstub、WiFi/蓝牙固件bcm43xx 系列图形栈选择自动在 VC4 KMS mesa 与 legacy userland 之间切换所有 machine 配置集中在conf/machine/目录每个.conf文件对应一块板子例如conf/machine/raspberrypi4.conf32 位 Pi 4与conf/machine/raspberrypi5.conf64 位 Pi 5。️ machine 配置的三层继承结构每个 board 的.conf文件都非常简短因为它们只负责两件事指定 CPU tune和包含公共配置。以conf/machine/raspberrypi4.conf为例第一行声明DEFAULTTUNE如cortexa7thf-neon-vfpv4require对应的 CPU tune 文件如arm/armv7a/tune-cortexa7.incinclude conf/machine/include/rpi-base.inc引入全部公共逻辑而conf/machine/include/rpi-base.inc又会进一步引入三个配套文件文件职责rpi-default-settings.inc默认行为SD 卡镜像类型、测试套件替换rpi-default-versions.inc内核版本偏好64 位默认 6.1832 位 6.12rpi-default-providers.inc图形库 provider 切换vc4graphics 特征存在时用 mesa否则用 userland这套薄 board 配置 厚公共 include的结构是理解整个 layer 的钥匙改公共行为改 include改单板差异改 .conf。 rpi-base.inc 精读8 个关键变量rpi-base.inc约 190 行核心逻辑可以归纳为以下几块内核镜像格式自动选择KERNEL_IMAGETYPEPi 的固件支持两种加载方式rpi-base.inc 根据RPI_USE_U_BOOT自动切换不用 u-boot32 位用zImage、64 位用Image由 Pi 固件直接加载启用 u-boot32 位用uImagebootm命令Pi 5 / armv8 则统一用Imagebooti所以你会看到raspberrypi5.conf里明确写了KERNEL_BOOTCMD booti而老 Pi 默认是bootm。设备树清单KERNEL_DEVICETREE变量分两段拼接RPI_KERNEL_DEVICETREE16 个基础.dtbbcm2708 → bcm2712 各代 SoCRPI_KERNEL_DEVICETREE_OVERLAYS70 个.dtbooverlay前面列出的就是这里各 board 的.conf可以用RPI_KERNEL_DEVICETREE ...覆盖基础清单。例如raspberrypi5.conf只保留 5 个 bcm2712 系列的 dtb而多板兼容机raspberrypi-armv8.conf则罗列了 Pi 2B 到 Pi 5 的全部 dtb。条件式依赖注入rpi-base.inc 通过oe.utils.conditional实现按需打包ENABLE_I2C 1 → 打包 i2c-dev / i2c-bcm2708 内核模块 ENABLE_IR 1 → 打包 gpio-ir 模块 对应 overlay ENABLE_GPIO_SHUTDOWN 1 → 打包 gpio-shutdown gpio-keys 模块这些开关在docs/extra-build-config.md中有完整说明配合ENABLE_CAN、ENABLE_W1等变量可以让同一份 layer 适配 CAN 总线、红外遥控、温度传感器等外设。启动分区的组装器make_dtb_boot_files这是 rpi-base.inc 中最巧妙的一个 Python 函数它遍历KERNEL_DEVICETREE为每个条目生成IMAGE_BOOT_FILES项并约定.dtbo与两个 map 文件要放到 SD 卡overlays/子目录基础.dtb放在根目录。之后classes/sdcard_image-rpi.bbclass里的IMAGE_CMD:rpi_sdimg会用mcopy把它们逐一拷入 FAT32 启动分区。 70 设备树 overlay 都装了什么打开rpi-base.inc中的RPI_KERNEL_DEVICETREE_OVERLAYS可以按用途分组记忆分类代表 overlay用途 音频hifiberry-dacplusadc、iqaudio-dac、wm8960-soundcardHiFiBerry / iQAudio 声卡 摄像头imx219、imx477、imx708相机模块 V2 / V3 传感器️ 显示vc4-kms-v3d(-pi4/-pi5)、pitft22/28/35KMS 显示与 PiTFT 屏 通信mcp2515-can0/can1、uart0~uart5含 pi5 变体CAN 总线、串口重映射️ GPIOgpio-shutdown、w1-gpio、gpio-key、dwc2关机按键、1-Wire、USB OTG 开关disable-bt(-pi5)、disable-wifi(-pi5)、rpi-poe禁用内置 BT/WiFi、PoE️ 映射overlay_map.dtb、hat_map.dtb让dtoverlay按名字解析注意uart 类 overlay 在 Pi 5 上有-pi5变体如uart0-pi5.dtbow1-gpio 同样如此——选 overlay 前先看你的板子代际。 设备树 overlay 选择技巧6 个常见场景overlay 打包进镜像 ≠ 自动生效。生效要靠启动分区的config.txt写一行dtoverlayxxx。meta-raspberrypi 提供了三种方式1. 用变量一键启用推荐在local.conf里设变量layer 会自动把对应 overlay 写进 config.txt 并打包所需内核模块ENABLE_CAN 1 # → dtoverlaymcp2515-can0 ENABLE_W1 1 # → dtoverlayw1-gpio ENABLE_IR 1 # → dtoverlaygpio-ir gpio-ir-tx2. 用 RPI_EXTRA_CONFIG 手动追加docs/extra-build-config.md中说明任何没有专用变量的选项都可以用RPI_EXTRA_CONFIG向 config.txt 追加任意行多行用\n分隔RPI_EXTRA_CONFIG \ndtoverlayimx219\n3. 显示模式的特殊变量 VC4DTBOKMS 显示由VC4DTBO控制各 machine 的默认值已写好Pi 5raspberrypi5.confvc4-kms-v3dPi 4 32 位vc4-kms-v3d通用 armv8vc4-fkms-v3d不想要 KMS 显示栈设DISABLE_VC4GRAPHICS 1machine 会摘掉vc4graphics特征图形 provider 自动切回 userland4. 多板镜像时 overlay 如何取舍如果目标覆盖多种板子raspberrypi-armv7/raspberrypi-armv8两个多板 machine默认 overlay 全集都会进镜像体积换兼容性单板 machine 则只带本板 dtb镜像更小、启动分区更干净——生产环境建议选单板 machine。5. 相机 overlay 与 CMA启用 imx219 / imx708 相机 overlay 时文档还提醒需在 config.txt 中设置cma相关参数docs/extra-build-config.md第 416 行起的 Enable Raspberry Pi Camera Module 一节有详细说明。6. 验证生效烧卡启动后在/proc/device-tree/或dmesg | grep -i dtbo中能看到已加载的 overlay 名称/boot/overlays/下应有你选用的.dtbo文件。 17 个 machine 配置速查表MACHINE板卡内核文件名SDIMG_KERNELIMAGE内核版本raspberrypiPi Barm1176kernel.img6.12raspberrypi0/-0-wifi/-0-2wPi Zero 系列kernel7(2) 系列6.12raspberrypi2/raspberrypi2-64Pi 2kernel7l.img / kernel8.img6.12 / 6.18raspberrypi3/raspberrypi3-64Pi 3 全系kernel7l.img / kernel8.img6.12 / 6.18raspberrypi4/raspberrypi4-64Pi 4 / 400kernel7l.img / kernel8.img6.12 / 6.18raspberrypi5Pi 5 / CM5kernel_2712.img6.18raspberrypi-cm/-cm3/-cm5-io-board计算模块随对应板—raspberrypi-armv7/raspberrypi-armv8多板兼容机多文件名见 include两个实用细节64 位 Pi 5 的串口是ttyAMA10其他板多为ttyS0或ttyAMA0远程调试时别配错Pi 4 32 位被锁定在 6.12 内核raspberrypi4.conf注释说明 6.18 已移除 Pi 4 的 32 位配置 新手避坑清单找不到启动文件先确认BOOTFILES_DIR_NAME默认bootfiles目录内容是否被rpi-bootfilesrecipe 正确部署EXTRA_IMAGEDEPENDS已自动加上它镜像里为何没有内核rpi-base.inc 末尾RDEPENDS:${KERNEL_PACKAGE_NAME}-base 是故意的——内核在 FAT32 分区rootfs 不重复携带overlay 改了不生效检查 config.txt 拼写dtoverlay靠overlay_map.dtb/hat_map.dtb解析名字两个 map 文件必须存在WiFi 没固件基础linux-firmware不含 RPi 无线固件需 layer 内linux-firmware-rpidistro提供各 machine 已通过MACHINE_EXTRA_RRECOMMENDS自动带上 bcm43xx 固件包想改默认内核版本改conf/machine/include/rpi-default-versions.inc里的PREFERRED_VERSION_linux-raspberrypi或在单个 machine 中覆盖如 Pi 4 32 位锁 6.12 就是这么做的 关键文件路径速查路径说明conf/machine/include/rpi-base.inc本文主角公共 machine 逻辑conf/machine/include/rpi-default-*.inc设置 / 版本 / provider 三件套conf/machine/raspberrypi*.conf17 个板级 machine 配置classes/sdcard_image-rpi.bbclassSD 卡镜像分区组装逻辑files/wic/sdimage-raspberrypi.wksWIC 布局描述文件docs/extra-build-config.mdconfig.txt 高级配置与 overlay 开关docs/layer-contents.md支持的 machine 与镜像清单掌握rpi-base.inc的继承链和 overlay 清单后你已能独立完成单板最小镜像构建 → 按外设追加 overlay → 生成可烧录 SD 卡镜像 的完整闭环。下一步建议从rpi-test-image跑通全流程再按docs/extra-build-config.md逐项开启你的外设。【免费下载链接】meta-raspberrypiYocto/OE BSP layer for the Raspberry Pi boards项目地址: https://gitcode.com/gh_mirrors/me/meta-raspberrypi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考