树莓派硬件

介绍

树莓派推出了 多种 系列的计算机：

• 旗舰 系列通常简称为“树莓派（Raspberry Pi）”，搭载了高性能硬件、完整的 Linux 操作系统及多种常见接口。其外形尺寸与信用卡大小相当。

• Zero 系列搭载了完整的 Linux 操作系统和最基本的接口，价格实惠，体积小，功耗低。

• 计算模块（Compute Module） 系列，一般简称为 "CM"。计算模块系列搭载了高性能硬件和完整的 Linux 操作系统，适合工业和嵌入式的小尺寸用途。计算模块的硬件与相应旗舰型号相当，但接口较少，甚至未板载 GPIO 引脚。用户需将计算模块接到一块单独的基板上，基板提供了使用接口和引脚。

此外，树莓派还推出了 Pico 系列微型多用途微控制器开发板。Pico 系列不支持 Linux，也不支持可移动存储，只能以把二进制文件刷到板载闪存存储器的方式进行编程。

旗舰系列

B 代表其搭载了以太网口。A 代表低成本产品线——其体积较小，不带以太网口，内存也不大；因受开发版高度限制，USB 接口也较少。

更多有关旗舰系列树莓派接口的信息，请参阅原理图和机械图。

Zero 系列

带 H 后缀的型号在 GPIO 引脚上预先焊接了排针。不带 H 后缀的型号未在 GPIO 引脚上焊接排针——用户需要手动焊接排针或使用第三方排针套件。

所有 Zero 系列型号搭载了以下连接功能：

• 一个 microSD 卡槽

• 一个 CSI 摄像头接口 (最早由 Zero 1.3 引入)

• 一个 mini HDMI 端口

• micro USB 端口 × 2（一个用于电源输入，另一个供外部设备使用）

计算模块系列

注意

某些计算模块的外形尺寸与 DDR2 SO-DIMM 相同，但不兼容其电气规格。

更多有关树莓派计算模块的信息，请参阅计算模块文档。

Pico 微控制器

带 H 后缀的型号在 GPIO 引脚上预先焊接了排针。不带 H 后缀的型号未焊接到 GPIO 引脚的排针——用户必须手动焊接排针或使用第三方排针套件。

有关各种树莓派 Pico 的更多信息，请参阅 Pico 文档。

电路图和机械图纸

各式树莓派开发板的原理图：

树莓派 5

• 机械图纸，PDF

• 树莓派 5 的 STEP 文件

树莓派 4B

• 原理图，版本 4.0

• 机械图纸，PDF

• 机械图纸，DXF

树莓派 3B+

• 原理图，修订版 1.0

• 机械图纸，PDF

• 机械图纸，DXF

• 外壳图纸，PDF

树莓派 3A+

• 原理图，版本 1.0

• 机械图纸，PDF

• 外壳图纸，PDF

树莓派 3B

• 原理图，修订版 1.2

• 机械图纸，PDF

• 机械图纸，DXF

树莓派 2B

• 原理图，修订版 1.2

树莓派 1B+

• 原理图，修订版 1.2

• 机械图纸，PDF

• 机械图纸，DXF

树莓派 1A+

• 电路图，修订版 1.1

注意

树莓派 3A+ 的机械图纸亦适用于树莓派 1A+。

树莓派 Zero 2 W

• 线路图

• 机械图纸，PDF

• 测试点

测试点

树莓派 Zero 2W 在生产过程中使用了许多测试点位置。

树莓派 Zero W

• 原理图，修订版 1.1

• 机械图纸，PDF

树莓派 Zero

• 原理图，修订版 1.3

• 机械图纸，PDF

• 外壳图纸，PDF——Zero 外壳

• 外壳图纸，PDF——GPIO 外壳

• 外壳图纸，PDF——相机外壳

产品合规性和安全性

所有树莓派产品均通过了充分的合规测试。更多有关信息，请参阅产品信息网站。

阻燃等级

树莓派设备使用的 PCB 符合 UL94-V0 标准。

注意

仅适用于 PCB。

树莓派合规支持

依据树莓派在合规测试期间的实际测试情况，合规支持计划的目标是消除处理合规问题的负担，为公司更轻松地将新产品推向消费者提供支持。它为用户提供了与 UL 公司的专门团队联系的机会，他们借助对树莓派的深入了解，评估和测试用户的产品。

了解更多关于树莓派合规支持计划的信息。

由树莓派提供支持

由树莓派提供支持的 Powered by RaspberryPi 计划，为想要使用树莓派 logo 形式的公司提供了一个流程，涵盖了搭载树莓派计算机、芯片的产品，以及由树莓派提供的服务。如果你希望进行申请流程，可在线操作。

已审批的设计合作伙伴

我们已审批的设计合作伙伴名单提供了一组我们密切合作并支持的咨询公司，它们能够在硬件、软件和机械领域提供付费设计服务。

频率管理和发热控制

在重负荷情况下，所有款式的树莓派，都会进行一定程度的发热管理，以避免过热。SoC 内置了温度传感器，GPU 上的软件会进行轮询，以确保温度不会超过我们设定的上限，所有型号均为 85°C。可以将此值设定为较低值，但不能提高上限。当设备接近极限时，芯片（Arm、GPU）上各种频率和电压（有时）会下降。这将减少产生的热量，使温度维持在一定范围内。

当核心温度在 80°C 和 85°C 间，Arm 核心会逐渐降频。如果温度达到 85°C，那么 Arm 核心和 GPU 都会进行降频。

树莓派 3B+ 采用了新型 PCB 技术，能提供更好的散热性能，提高热质量。此外，还引入了软温度限制，旨在最大化延长设备在达到硬限制 85°C 之前的“高性能”时间。当达到软限制时，时钟速度从 1.4GHz 降至 1.2GHz，并略微降低操作电压。这减缓了温度升高的速度：我们以更长时间的 1.2GHz 代替了短暂运行的 1.4GHz。在默认情况下，软限制为 60°C：可通过 config.txt 中的参数 temp_soft_limit 进行更改。

树莓派 4B 沿用了树莓派 3B+ 的 PCB 技术，以帮助散热。目前尚未实施软限制。

使用 DVFS

注意

此 DVFS 讨论仅适用于树莓派 4B、400 和 计算模块 4。

树莓派 4 采取了动态电压频率调节（DVFS）。该技术使树莓派 4 设备能在保持性能不变的同时降低运行温度。

固件会监控 SoC 内部的各种时钟（例如 Arm、Core、V3D、ISP、H264、HEVC），当它们未全速运行时，供给给这些时钟驱动的芯片部分的电压，将环比全速时略微降低。事实上，仅提供一定的电压就足以确保其以特定运行水准正常运行。这可以显著降低 SoC 的功耗，从而了削减了总发热量。

由于可能引发系统稳定性故障，特别是在使用电压降低固定时钟外设（例如 PCIe）时，存在潜在的系统稳定性故障。有三种 DVFS 模式，可在 /boot/firmware/config.txt 中配置，特征如下。大多数设备应使用 dvfs=3，不带显示的设备可能会因其较低功耗降低而从 dvfs=1 受益，但会面临 PCIe 稳定性问题的风险。

注意

树莓派 5 已经移除了这个参数，并将始终处于模式 3。

此外，还采用了更细粒度的 CPU 调度器，用来更精细地控制 ARM 核心频率，这意味着 DVFS 效果更佳。现在的步进频率为 600MHz、750MHz、1000MHz 和 1500MHz。这些步进在 SoC 限流时可能有益，意味着几乎不会完全降至 600MHz，从而大幅改善了全负载时的性能。

默认的 CPU 调度器是 ondemand。可以手动调用软件包 cpufrequtils 中的命令 cpufreq-set 更改调度器来减少空闲功耗：

$ sudo apt install cpufrequtils
$ sudo cpufreq-set -g powersave

测量温度

由于树莓派设备使用的 SoC 架构，若在树莓派系统发行版中使用了上游的温度监控代码（如基于 Linux 的温度测量），可能并不准确。但是，命令 vcgencmd 能够提供准确且即时的 SoC 温度的实时数值，因为 vcgencmd 同 GPU 直接通信：

$ vcgencmd measure_temp

添加散热片

由于内置节流功能，不用散热片也不会造成 SoC 过热损坏。不过，安装散热片和小型风扇可缓解发热限流，改善性能。要获得最佳气流，略微改善散热效果，可考虑把树莓派竖着放。

风扇套件

用于辅助散热，树莓派 5 有两款官方风扇可选：

• 主动散热器

• 用于树莓派 5 的外壳

这两款均应插入至主板右上方的风扇连接器（四针 JST-SH PWM），位于 40 引脚 GPIO 排针和 USB 2.0 之间。风扇连接器与 USB 外围设备一同受电流限额。我们建议超频用户使用主动散热器外壳，因为它有更好的散热能力。

以上两种可选官方配件均由树莓派固件主动控制。随着树莓派的温度升高，风扇的反应如下：

• 在 50°C 以下，风扇不会转动（0% 速度）

• 在 50°C 时，风扇缓慢转动（30% 速度）

• 在 60°C 时，风扇转速提高至中速（50% 速度）

• 在 67.5°C 时，风扇转速提高至高速（70% 速度）

• 在 75°C 时，风扇转速达到全速（100% 速度）

温度下降时，应用相同的行为，伴有 5°C 的滞后性；当温度下降到低于上述每个阈值 5°C 时，风扇速度才会放缓。

在启动时，风扇会自动运转，以查看转速控制，并检查风扇是否旋转。如果可以，则启用设备树驱动 cooling_fan。在默认情况下，该驱动位于 bcm2712-rpi-5-b.dtb，但可以用 status=disabled 进行修改。

风扇连接器引脚图

风扇连接器是一个间距 1 mm 的 JST-SH 插座，包含以下四个引脚：

树莓派启动 EEPROM

树莓派 4、400、5，计算模块 4、4S 计算机使用 EEPROM 启动系统。其他型号的树莓派 计算机使用位于启动文件系统中的 bootcode.bin 文件。

注意

在 GitHub 存储库 rpi-eeprom 中，你可以找到用于创建 rpi-eeprom 的脚本和预编译的二进制文件。

诊断引导

如果在引导过程中出现错误，会用绿色 LED 灯传递故障信息。更新后的引导加载程序会在 HDMI 显示器上输出诊断信息。

更新引导程序

有多种方法来更新你树莓派的引导程序。

树莓派 5、树莓派 4、树莓派 400

树莓派操作系统会自动更新引导加载程序来进行重要的错误修复。要手动更新引导加载程序/更改启动顺序，请使用 raspi-config。

使用树莓派启动盘制作工具来更新引导加载程序

树莓派启动盘制作器提供了一个图形界面，用于更新引导加载程序并选择引导模式。

1. 下载树莓派启动盘制作工具

2. 选择一张未使用的存储卡（引导加载程序镜像会格式化整张卡）

3. 启动树莓派启动盘制作工具

4. 选择 选择操作系统（Choose OS）

5. 选择 Misc utility images

6. 为你的树莓派选择 Bootloader (树莓派 400 属于 4 系列)

7. 选择引导模式：存储卡（建议）、USB、网络

8. 选择 存储卡 然后 写入（Write）

9. 单击 确认（Yes） 继续

10. 使用新的镜像引导树莓派，请等待至少十秒钟

11. 当绿色状态指示灯有规律的闪烁，且 HDMI 显示绿屏后，你就已成功写入引导程序了

12. 断开树莓派的电源，拔出存储卡

使用 raspi-config 来更新引导加载程序

要在树莓派系统上更改启动模式、变动引导加载程序版本，请运行 raspi-config。

1. 更新树莓派系统，下载软件包 rpi-eeprom 的最新版本。

2. 运行 sudo raspi-config。

3. 选择 Advanced Options。

4. 选择 Bootloader Version。

5. 选择 Default 可恢复出厂设置、选择 Latest 可获取最新发布的引导程序。

6. 使用 sudo reboot 重启。

更新引导程序配置

引导加载程序 default 版本即最新的出厂默认固件镜像。它提供了关键的错误修复、硬件支持，并且特性均在 latest 版本中经过测试，然后定期更新。latest 版引导加载程序的更新更为频繁，包含了最新的修复和改进。

专业用户可以切换到 latest 版引导加载程序以获得最新功能。

运行以下命令启动 raspi-config。

$ sudo raspi-config

切换到 Advanced Options，然后选择 Bootloader Version。选择 Latest 并选择 Yes 确认。选择 Finish 确认重启。重启后，再次打开命令提示符更新你的系统：

$ sudo apt update

如运行 sudo rpi-eeprom-update，你将看到引导加载程序的更新版本是 latest 发行版。

*** UPDATE AVAILABLE ***
BOOTLOADER: update available
   CURRENT: Thu 18 Jan 13:59:23 UTC 2024 (1705586363)
    LATEST: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
   RELEASE: latest (/lib/firmware/raspberrypi/bootloader-2711/latest)
            Use raspi-config to change the release.

  VL805_FW: Using bootloader EEPROM
     VL805: up to date
   CURRENT: 000138c0
    LATEST: 000138c0

现在，你可以更新你的引导加载程序。

$ sudo rpi-eeprom-update -a
$ sudo reboot

重启，然后运行 sudo rpi-eeprom-update。现在你应该看到 CURRENT 的日期已更新为引导程序的最新版本之日期。

BOOTLOADER: up to date
   CURRENT: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
    LATEST: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
   RELEASE: latest (/lib/firmware/raspberrypi/bootloader-2711/latest)
            Use raspi-config to change the release.

  VL805_FW: Using bootloader EEPROM
     VL805: up to date
   CURRENT: 000138c0
    LATEST: 000138c0

查阅当前引导程序配置

要查看当前运行的引导程序使用之配置，请运行以下命令：

$ rpi-eeprom-config

从引导加载程序镜像中读取配置

要从引导加载程序镜像中读取配置：

$ rpi-eeprom-config pieeprom.bin

编辑当前的引导加载程序配置

执行以下命令可将当前引导加载程序配置加载到文本编辑器。当关闭编辑器后，rpi-eeprom-config 将更新后的配置应用于最新的可用引导加载程序版本，并使用 rpi-eeprom-update 在系统重启时应用更新：

$ sudo -E rpi-eeprom-config --edit
$ sudo reboot

如果更新后的配置与原配置相同、或为空，则不会进行任何更改。

编辑器取决于环境变量 EDITOR。

应用已保存的配置

以下命令将 boot.conf 应用于最新可用的引导加载程序镜像，使用 rpi-eeprom-update 在系统重启时应用更新。

$ sudo rpi-eeprom-config --apply boot.conf
$ sudo reboot

自动更新

rpi-eeprom-update 的 systemd 服务会在启动时运行，且在新镜像可用时应用更新，自动迁移当前的引导加载程序配置。

要禁用自动更新：

$ sudo systemctl mask rpi-eeprom-update

要重新启用自动更新：

$ sudo systemctl unmask rpi-eeprom-update

注意

如果设置了 FREEZEVERSION 引导加载程序配置，则更新服务将跳过自动更新。这样可以避免在安装了多个操作系统、更换存储卡时逐个禁用更新服务的需要。

rpi-eeprom-update

树莓派操作系统使用脚本 rpi-eeprom-update 实现自动更新服务。该脚本还可以通过交互方式运行、进行封装，创建定制的引导加载程序更新服务。

读取当前引导加载程序版本：

$ vcgencmd bootloader_version

检查是否有可用更新：

$ sudo rpi-eeprom-update

安装更新：

$ sudo rpi-eeprom-update -a
$ sudo reboot

取消待定更新：

$ sudo rpi-eeprom-update -r

安装特定的引导程序镜像:

$ sudo rpi-eeprom-update -d -f pieeprom.bin

参数 -d 让 rpi-eeprom-update 使用指定的镜像文件中的配置，而不是自动迁移当前的配置。

打开自带文档:

$ rpi-eeprom-update -h

引导加载程序发布状态

固件发布状态对应于引导加载程序固件镜像的特定子目录（ /lib/firmware/raspberrypi/bootloader/... ），可以更改以选择不同的发行版本。

• default：用于支持新硬件、关键错误修复，并通过在 latest 版本测试过的新功能的定期更新。

• latest：当新功能可用时进行更新

由于发布状态字符串仅是一个子目录名，因此你可以创建自己的发行版本，例如固定发行或自定义网络引导配置。

更改启动加载程序版本

注意

你可以通过编辑 /etc/default/rpi-eeprom-update 文件，把条目 FIRMWARE_RELEASE_STATUS 更改为适当的流来更改在更新过程中使用的发布版本。

更新启动加载器配置文件中的启动加载器镜像

以下命令将 pieeprom.bin 中的启动加载器配置替换为 boot.conf 并将新镜像写入 new.bin ：

$ rpi-eeprom-config --config boot.conf --out new.bin pieeprom.bin

recovery.bin

在开机时，BCM2711、BCM2712 上的 ROM 会在存储卡的启动分区的根目录中查找文件 recovery.bin。如果能找到一个有效的 recovery.bin，那么 ROM 就会执行这个文件，而非读取 EEPROM。该机制可确保始终能对引导加载程序闪存恢复出厂设置。

欲了解更多信息，请参阅 EEPROM 启动流程。

引导加载程序更新文件

• 如果引导加载程序更新镜像为 pieeprom.upd，则更新完成后 recovery.bin 会被重命名为 recovery.000，然后系统会重启。由于检测不到 recovery.bin，ROM 将从 SPI 闪存加载新近更新的引导加载程序，然后正常启动操作系统。

• 如果引导加载程序更新镜像为 pieeprom.bin，那么更新完成后 recovery.bin：如更新成功，HDMI 显示绿屏，绿色状态 LED 快速闪烁；如果更新失败，HDMI 显示红屏，并且通过状态 LED 传递错误代码。

• .sig 文件包含了相应镜像文件的十六进制 sha256 校验和；将来可能会添加其他字段。

• 在 BCM2711、BCM2712 上的 ROM 查找 recovery.bin 的功能，不支持 USB 大容量存储设备及 TFTP。而且，更新版本的引导加载程序已支持自更新功能，使引导加载程序能够自己重新刷新 SPI 闪存。请参阅引导加载程序配置页面上的 ENABLE_SELF_UPDATE。

• EEPROM 更新的临时文件会在启动时由 rpi-eeprom-update 服务自动删除。

若要获取有关 rpi-eeprom-update 配置文件的更多信息，请参阅 rpi-eeprom-update -h。

EEPROM 写保护

引导加载程序和 VLI EEPROM 都支持硬件写保护。有关如何在更新 EEPROM 时启用此功能的更多信息，请参阅参数 eeprom_write_protect。

树莓派 4 的启动诊断

从树莓派 4 引导加载程序 2020-04-16 版本开始，诊断信息会出现在 HDMI 显示器上。要查看诊断信息，请关闭树莓派 4，拔掉存储卡，然后重启。在接入的显示器上应该会出现类似如下的诊断信息。

该诊断页面也会出现在以下情况：引导加载程序无法引导插入的存储卡、无法进行网络引导；可能因为：存储卡中没有可引导的镜像、存储卡是假冒伪劣产品、网络引导配置错误。

只要显示了诊断页面，就只能通过重新插拔设备电源（即拔掉然后重新插上电源）来重启。

诊断页面最顶部的一行说明了树莓派型号、内存容量。二维码是指向下载页面的链接。

诊断信息如下：

可以使用参数 DISABLE_HDMI 禁用此显示器，请参阅引导加载程序配置。

注意

该功能仅用于诊断引导故障；它并非可交互的引导程序。如果你需要交互式引导程序，请考虑使用类似 U-Boot 的工具。

树莓派引导模式

树莓派有多种不同的引导阶段。本文档解释了引导模式的工作原理，以及哪些引导模式支持 Linux 引导。

特殊 bootcode.bin 专用启动模式

基于 BCM2837 的树莓派可从 USB 设备和以太网引导 - 也就是说，树莓派 2B v1.2，树莓派 3B 和树莓派 3B+（由于树莓派 3A+ 没有内置以太网接口，无法进行网络引导）。此外，所有早于树莓派 4 的树莓派型号可以使用仅 bootcode.bin 方法启用 USB 设备引导。

注意

自树莓派 4 以降，旗舰级设备不再使用 bootcode.bin 这个文件。因为这些设备使用了板载 EEPROM 芯片中的引导加载程序。更多信息，请参阅 EEPROM 引导流程和 SPI 引导 EEPROM 的文档。

把格式化存储卡为 FAT32，将最新的 bootcode.bin 复制到里面。把存储卡插入到树莓派中。从存储卡加载 bootcode.bin 以后，树莓派就能使用 USB 主机模式启动了。

这对于基于 BCM2835、BCM2836 芯片的树莓派 1、2 和 Zero 型号非常有用，在树莓派 3 无法启动的情况下（同烧录到 BCM2837A0 中的启动代码相比，最新的 bootcode.bin 为树莓派 3B 提供了额外的错误修复）。

若即使使用了这个 bootcode.bin，你的大容量存储设备还是无法使用，请在存储卡上新建一个名为“timeout”的文件。这将使其等待大容量存储设备初始化的时间延长到 6 秒。

启用 bootcode.bin 串口

注意

适用于在树莓派 4 发布前的开发板。

有关使用 EEPROM 引导加载程序启用串口的信息，请参阅引导加载程序配置文档。

可以启用早期阶段的串口来调试引导问题（与上述 bootcode.bin 仅引导模式非常有用）。要做到这一点，请确保你的固件版本是新的（包括 bootcode.bin）。要检查当前固件是否支持串口：

$ strings bootcode.bin | grep BOOT_UART

要从 bootcode.bin 启用串口：

$ sed -i -e "s/BOOT_UART=0/BOOT_UART=1/" bootcode.bin

接下来，将合适的 USB 串口线连接到计算机（尽管你可能会发现，最简单的方法就是使用 USB 串口线，因为它可以在无需设置烦人的 config.txt 的情况下直接使用树莓派）。在树莓派（计算模块）上使用单独的引脚 6、8 和 10（GND、GPIO14、GPIO15）。

然后在 Linux（macOS）上使用 screen。在 Windows 上使用 putty 来连接到串口。

设置串口接收速率为 115200-8-N-1，然后启动你的树莓派。你应该可即时从设备上获得 bootcode.bin 的串行输出。

USB 启动模式

USB 有两种独立的启动模式:

• USB 设备启动

• USB 主机启动

固件会根据 OTP 位在引导时选择两种模式中的一种。用两位控制 USB 引导。第一位启用 USB 设备引导，为默认设置；第二位启用 USB 主机引导。

如果设置了 USB 主机引导模式位，则处理器会读取 OTGID 引脚来决定是作为主机引导（驱动到零，就像在所有树莓派 A/B+ 上一样）还是作为设备引导（保持漂浮）。树莓派 Zero 通过 USB 连接器可以访问 OTGID 引脚；计算模块可以通过边缘连接器访问 OTGID 引脚。

其他某些 OTP 位可允许某些 GPIO 引脚选择引导模式。

USB 设备引导模式

注意

USB 引导适用于旗舰级的计算模块系列，Zero 系列和衍生的 A 款。

当启用此引导模式（通常在无法从存储卡引导后），树莓派 将其置为 USB 设备模式，等待主机发送的 USB 重置。在 Github 上可以找到示例代码，展示主机需如何与树莓派进行通信。

主机首先通过控制端点 0 向设备发送一个结构。这包含了启动的大小和签名（未启用安全性，因此无需签名）。其次，代码通过端点 1 传输（bootcode.bin）。最后，设备将用以下代码之一回复：

• 0 - 成功

• 0x80 - 失败

USB 主机引导模式

注意

自树莓派计算模组 3、Zero 系列 2 W、树莓派 2B（1.2 版）、树莓派 3B 以及自树莓派 3B+ 以降，主机引导功能可在计算模块系列和所有旗舰系列设备上使用。树莓派 3A+ 支持大容量存储引导，但不支持网络引导。

USB 主机引导模式采用以下逻辑:

• 启用 USB 接口 并等待 D+ 线拉高，表示连接了 USB 2.0 设备（我们只支持 USB2.0

• 如果设备是一款集线器：

  • 启用所有集线器的下游接口的电源

  • 对于每个端口，最多循环两秒（如果 program_usb_boot_timeout=1 已设置，则为 5 秒）

    • 释放复位并等待 D+ 被拉高以指示设备已连接

    • 如果检测到设备：

      • 发送“获取设备描述符”

        • 如果 VID == SMSC 并且 PID == 9500

          • 将设备添加到以太网设备列表

        • 如果 class 接口是大容量存储设备

          • 把设备添加到大容量存储设备列表

• 否则

  • 枚举单个设备

• 浏览大容量存储设备列表

  • 从大容量存储设备启动

• 浏览以太网设备列表

  • 从以太网引导

在树莓派 3B，3A+ 和 3B+ 上，默认禁用主机引导。要启用 USB 主机引导，请将 program_usb_boot_mode=1 这一行添加到 /boot/firmware/config.txt 的末尾。

警告

任何对 OTP 的修改都是永久性的，无法撤销。 。 在树莓派 3A+ 上，将 OTP 位设置为启用 USB 主机引导模式将永久性地禁止其以 USB 设备模式启动。

USB 大容量存储启动

注意

自计算模块 3，Zero 2 W 起的 Zero 系列，以及自树莓派 2B（版本 1.2）起的所有旗舰系列设备均可使用。

USB 大容量存储启动能让你从 USB 大容量存储设备（如闪存驱动器、USB 磁盘）启动树莓派。在连接 USB 设备时（尤其是硬盘和 SSD），需要注意它们的功耗要求。接入多个磁盘通常需要额外的外部电源，可以是带电源的硬盘盒、带供电的 USB 集线器。

注意

树莓派 4B 之前的型号存在已知问题，导致可能无法从某些 USB 设备启动。

带有 EEPROM 引导加载程序的设备

树莓派 4 和更新款的旗舰系列设备以及自计算模块 4 和 4S 起，支持默认情况下的 USB 引导，只要在 BOOT_ORDER 配置中指定 USB 引导。

注意

早期版本的树莓派 4 可能需要更新引导加载程序才能从 USB 启动。

注意

计算模块 4 的早期版本可能需要更新引导加载程序才能从 USB 启动。

树莓派 3B+

树莓派 3B+ 支持开箱即用的 USB 大容量存储启动。

树莓派 2B，3A+，3B，CM3，CM3+，Zero 2 W

在树莓派 2B v1.2，3A+，3B，Zero 2 W 和计算模块 3 和 3+ 上，必须先启用 USB 主机启动模式。才能从 USB 大容量存储启动和网络启动。

注意

树莓派 3A+ 和 Zero 2 W 不支持网络启动。 要启用这些设备的 USB 主机启动模式，请在 OTP（一次可编程）内存中设置 USB 主机位。要设置该位，请从包含以下行的存储卡引导 /boot/firmware/config.txt。设置该位后，你可以在没有存储卡的情况下从 USB 启动。

使用 OTP 启用 USB 主机启动模式

警告

对 OTP（一次可编程）内存所做的一切修改都是永久性的，无法撤销。 。 在树莓派 3A+ 上，设置 OTP 位来启用 USB 主机启动模式将永久禁止该树莓派以 USB 设备模式启动。

使用内置树莓派系统的存储卡来编程 OTP 位。

要启用 USB 主机启动模式，请将以下行添加到 config.txt 中：

program_usb_boot_mode=1

然后使用 sudo reboot 重启你的树莓派。要检查 OTP 是否已正确编程，请运行以下命令：

$ vcgencmd otp_dump | grep 17:
17:3020000a

如果输出显示 0x3020000a，则 OTP 已成功编程。如果看到不同的输出，请再次尝试编程过程。确保 config.txt 末尾没有空行。

你现在可以像从存储卡启动一样从 USB 大容量存储设备启动。有关更多信息，请参阅以下部分。

从 USB 大容量存储设备启动

过程与存储卡相同：把操作系统镜像写入 USB 存储设备。

存储设备准备就绪后，连接驱动器并启动树莓派，需注意外部驱动器的额外 USB 电源需求。

大约 5 到 10 秒后，树莓派应该开始启动了。如果接入的显示器上出现彩虹屏。请确定未将存储卡插入树莓派，因为倘若插入了存储卡，树莓派将优先从存储卡启动。

查阅引导模式文档可了解引导顺序和备选引导模式（网络、USB 设备、GPIO 或存储卡启动）。

已知问题

• 检查可引导 USB 设备的默认超时时间为 2 秒。某些闪存驱动器和硬盘启动速度过慢。可以将此超时时间延长到 5 秒（需在存储卡中新建文件 timeout），但要注意某些设备可能需要更长时间来响应。

• 某些闪存驱动器采用了极为罕见的协议，引导码无法处理，因此造成不兼容。

特殊 bootcode.bin——仅引导模式

对于树莓派 2B v1.2、3A+、3B 和 3B+，如果你无法使用特定的 USB 设备来启动，你可以使用 bootcode.bin 专用启动模式。树莓派仍会从存储卡启动，但只会从存储卡中读取 bootcode.bin；你操作系统的其余部分仍存储在 USB 设备。

硬件兼容性

在从 USB 大容量存储设备启动之前，请验证该设备在 Linux 下是否正常工作。使用存储卡引导，插入 USB 大容量存储设备。USB 设备应显示为可移动驱动器。这在使用 USB SATA 转换设备时尤其重要，该适配器可能由引导加载程序支持大容量存储模式，但如果 Linux 选择 USB 附加 SCSI-UAS 模式，则有概率不兼容。

使用硬盘驱动器（HDD）通常需要带供电的 USB 集线器。即使一切看起来正常，如果 USB 集线器没带电源，你可能仍会遇到间歇性故障。

多个可引导驱动器

在搜索可引导分区时，引导加载程序会同时扫描所有 USB 大容量存储设备，并选择首个响应的设备。如果引导分区没有找到合适的 start.elf 文件，则引导加载程序将尝试下一个可用设备。没有根据 USB 拓扑结构指定引导设备的方法；这将减缓引导速度，带来不必要的配置复杂性。

注意

可使用 config.txt 文件条件过滤器来选择复杂设备配置中的备用固件。

网络引导

本节描述了树莓派 3B、3B+ 和 2B v1.2 上的网络引导工作原理。

在树莓派 4 和树莓派 5 上，网络引导是在 EEPROM 中的第二阶段引导加载程序中实现的。更多信息，请参阅树莓派 4 引导加载程序配置。

我们还有关于设置网络引导系统的教程。

仅适用于上述型号树莓派中内置的有线适配器进行网络引导。无线局域网引导不受支持，也不支持从其他有线网络设备引导。

网络引导流程

要进行网络引导，引导 ROM 执行以下操作：

• 初始化板载以太网设备（Microchip LAN9500/LAN7500）

• 发送 DHCP 请求（使用厂商类别标识符 DHCP 选项 60 设置为 PXEClient:Arch:00000:UNDI:002001)

• 接收 DHCP 回复

• （可选）接收 DHCP 代理回复

• ARP 到 tftpboot 服务器

• ARP 回复包含 tftpboot 服务器以太网地址

• TFTP RRQ bootcode.bin

  • 服务器响应 TFTP 错误响应，并附带文本错误消息，文件未找到

  • 服务器会回复包含文件头部块编号的数据块（512 B）中的第一个块，文件已存在

    • 树莓派回复 TFTP ACK 数据包，包含块编号，并重复直到最后一个非 512 B 块

• TFTP RRQ bootsig.bin 下载请求

  • 这通常会产生报错 file not found。这是预料之中的，TFTP 引导服务器应该能够处理它。

从此刻开始，bootcode.bin 代码继续加载系统。它将尝试访问的第一个文件是 <serial_number>/start.elf。如果这不会导致错误，那么要读取的其他文件将会在前面加上 serial_number。这很有用，因为它使你能够为你的树莓派创建具有不同 start.elf /内核的独立目录。

要获取设备的序列号，你可以尝试使用这种引导模式，并查看使用 tcpdump / wireshark 访问的文件，或者你可以运行标准的树莓派系统存储卡和 cat /proc/cpuinfo。

如果你将所有文件放入 TFTP 目录的根目录中，那么随后所有的文件都将从那里访问。

调试网络引导模式

首先要检查的是 OTP 位是否被正确编程。为此，你需要将 program_usb_boot_mode=1 添加到 config.txt，然后重启（使用可以正确引导到树莓派系统的标准存储卡）。完成后，你应该可以执行以下操作：

$ vcgencmd otp_dump | grep 17:

如果第 17 行包含 3020000a，则 OTP 已正确编程。现在，你可以拔掉存储卡，插入以太网了，然后在树莓派上电约 5 秒后，以太网指示灯应该被点亮。

要在服务器上捕获以太网数据包，请在 tftpboot 服务器上（如果未使用，则在 DHCP 服务器上）使用 tcpdump。否则，你将无法看到发送的数据包，因为网络交换机不是集线器！

$ sudo tcpdump -i eth0 -w dump.pcap

将从 eth0 写入文件 dump.pcap 中的所有内容。然后，你可以对数据包进行后处理或上传到 cloudshark 进行通信。

DHCP 请求/响应

至少你应该看到一个类似以下内容的 DHCP 请求和回复：

6:44:38.717115 IP (tos 0x0, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 348)
    0.0.0.0.68 > 255.255.255.255.67: [no cksum] BOOTP/DHCP, Request from b8:27:eb:28:f6:6d, length 320, xid 0x26f30339, Flags [none] (0x0000)
	  Client-Ethernet-Address b8:27:eb:28:f6:6d
	  Vendor-rfc1048 Extensions
	    Magic Cookie 0x63825363
	    DHCP-Message Option 53, length 1: Discover
	    Parameter-Request Option 55, length 12:
	      Vendor-Option, Vendor-Class, BF, Option 128
	      Option 129, Option 130, Option 131, Option 132
	      Option 133, Option 134, Option 135, TFTP
	    ARCH Option 93, length 2: 0
	    NDI Option 94, length 3: 1.2.1
	    GUID Option 97, length 17: 0.68.68.68.68.68.68.68.68.68.68.68.68.68.68.68.68
	    Vendor-Class Option 60, length 32: "PXEClient:Arch:00000:UNDI:002001"
	    END Option 255, length 0
16:44:41.224619 IP (tos 0x0, ttl 64, id 57713, offset 0, flags [none], proto UDP (17), length 372)
    192.168.1.1.67 > 192.168.1.139.68: [udp sum ok] BOOTP/DHCP, Reply, length 344, xid 0x26f30339, Flags [none] (0x0000)
	  Your-IP 192.168.1.139
	  Server-IP 192.168.1.1
	  Client-Ethernet-Address b8:27:eb:28:f6:6d
	  Vendor-rfc1048 Extensions
	    Magic Cookie 0x63825363
	    DHCP-Message Option 53, length 1: Offer
	    Server-ID Option 54, length 4: 192.168.1.1
	    Lease-Time Option 51, length 4: 43200
	    RN Option 58, length 4: 21600
	    RB Option 59, length 4: 37800
	    Subnet-Mask Option 1, length 4: 255.255.255.0
	    BR Option 28, length 4: 192.168.1.255
	    Vendor-Class Option 60, length 9: "PXEClient"
	    GUID Option 97, length 17: 0.68.68.68.68.68.68.68.68.68.68.68.68.68.68.68.68
	    Vendor-Option Option 43, length 32: 6.1.3.10.4.0.80.88.69.9.20.0.0.17.82.97.115.112.98.101.114.114.121.32.80.105.32.66.111.111.116.255
	    END Option 255, length 0

Vendor-Option Option 43 包含了回复的重要部分。这个部分必须包含字符串“Raspberry Pi Boot”。由于引导 ROM 中的一个错误，你可能需要在字符串末尾添加三个空格。

TFTP 文件读取

当供应商参数被正确指定时，你将看到随后发送的 TFTP RRQ 数据包。RRQ 可以通过第一个数据块或错误消息来回复，表明文件未找到。在少数情况下，他们甚至会收到第一个数据包，然后由 树莓派 中止传输（当检查文件是否存在时会发生这种情况）。下面的示例仅包括三个数据包：原始读取请求、第一个数据块（始终是包含一个标头和 512 B 数据的 516 B，尽管最后一个块始终少于 512 B 且可能为零长度），以及第三个数据包（包含与数据块中帧编号匹配的确认帧号）。

16:44:41.224964 IP (tos 0x0, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 49)
    192.168.1.139.49152 > 192.168.1.1.69: [no cksum]  21 RRQ "bootcode.bin" octet
16:44:41.227223 IP (tos 0x0, ttl 64, id 57714, offset 0, flags [none], proto UDP (17), length 544)
    192.168.1.1.55985 > 192.168.1.139.49152: [udp sum ok] UDP, length 516
16:44:41.227418 IP (tos 0x0, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 32)
    192.168.1.139.49152 > 192.168.1.1.55985: [no cksum] UDP, length 4

已知问题

以太网引导模式有一些已知问题。由于引导模式的实现在芯片本身，除了使用仅包含 bootcode.bin 文件的存储卡外，没有其他解决方法。

DHCP 请求在五次尝试后超时

树莓派将尝试进行五次 DHCP 请求，每次间隔五秒，总共持续 25 秒。如果服务器在此期间无法响应，树莓派将进入低功耗状态。除非使用存储卡上的 bootcode.bin，否则没有解决办法。

不支持在不同子网上的 TFTP 服务器

在树莓派 3B+ (BCM2837B0) 中已修复。

DHCP 中继故障

DHCP 检查还检查了跳数值是否为 1，而在 DHCP 中继情况下，它不会这样。

在树莓派 3A+ 中已修复。

树莓派启动字符串

在 DHCP 回复中，字符串“Raspberry Pi Boot”由于计算字符串长度的错误而需要占用额外三个空格。

在树莓派 3B+ 中已修复。

DHCP UUID 常量

DHCP UUID 设置为常量值。

已在树莓派 3A+ 修复；该值设置为 32 位序列号。

ARP 检查可能在 TFTP 事务中间无法响应

树莓派只会在初始化阶段响应 ARP 请求；一旦开始传输数据，它将无法继续响应。

已在树莓派 3 A+ 修复。

DHCP 请求/回复/确认序列未正确实现

在启动时，树莓派广播 DHCPDISCOVER 数据包。DHCP 服务器回复一个 DHCPOFFER 数据包。然后树莓派继续启动而不执行 DHCPREQUEST 或等待 DHCPACK。这可能导致两个不同设备被提供相同的 IP 地址并在未正确分配给客户端的情况下使用它。

不同的 DHCP 服务器在这种情况下有不同的行为。dnsmasq（取决于设置）将散列 MAC 地址以确定 IP 地址，并 ping 该 IP 地址以确保它尚未被使用。这减少了这种情况发生的机会，因为这需要在散列中发生碰撞。

GPIO 启动模式

注意

GPIO 引导模式仅适用于树莓派 3A+、3B、3B+，计算模块 3、3+。

老的树莓派可以配置：以在接通电源时使用连接到 GPIO 连接器的硬件选择启动模式。这是通过在 SoC 的 OTP 存储器中设置位来完成的。一旦设置了这些位，它们会永久性分配五个 GPIO，以便进行选择。只要设置了 OTP 位，就无法撤销。你应该仔细考虑是否启用此功能，因为这五个 GPIO 针脚将始终控制引导。尽管在树莓派引导后可以使用这些 GPIO 进行其他功能，但你必须进行额外设置，才能在树莓派引导时启用所需的启动模式。

要启用 GPIO 引导模式，请将以下行添加到 config.txt 文件中：

program_gpio_bootmode=n

其中 n 是你希望使用的 GPIO 的 bank。然后重启树莓派一次，以使用此设置编程 OTP。Bank 1 是 GPIO 22-26，Bank 2 是 GPIO 39-43。除非你有一个计算模块，否则必须使用 bank 1：Bank 2 上的 GPIO 仅在计算模块上可用。由于 OTP 位的排列方式，如果你首先为 Bank 1 编程 GPIO 引导模式，那么稍后可以选择 Bank 2。反之不成立：一旦选择 Bank 2 作为 GPIO 引导模式，就无法选择 Bank 1。

一旦启用了 GPIO 引导模式，树莓派将不再启动。你必须拉高至少有关一个引导模式的 GPIO 引脚，才能启动树莓派。

引脚分配

树莓派 3B 和计算模块 3

以上表格中的 USB 选项同时选择 USB 设备引导模式和 USB 主机引导模式。要使用 USB 引导模式，必须在 OTP 存储器中启用。有关更多信息，请参阅 USB 设备引导和 USB 主机引导。

后续的树莓派 3B（带金属盖的 BCM2837B0）、树莓派 3A+、3B+ 和计算模块 3+

注意

各种启动模式按照 GPIO 线的数字顺序尝试，即 SD0，然后 SD1，然后 NAND 等等。

启动流程

SD0 是博通的存储卡/MMC 接口。当 SoC 内部的引导 ROM 运行时，SD0 将始终连接到内置的 microSD 卡。在带有 eMMC 设备的计算模块上，SD0 连接到该设备；在精简版（Lite）计算模块上，SD0 可用于边缘连接器，并连接到 CMIO 载板上的 microSD 卡。SD1 是 Arasan 存储卡/MMC 接口，亦支持 SDIO。所有具有内置无线局域网的树莓派都使用 SD1 通过 SDIO 连接到无线芯片。

GPIO 针脚的默认上拉电阻为 50KΩ，详见 BCM2835 ARM 外围设备数据表第 102 页。推荐使用 5KΩ 的上拉电阻将 GPIO 针脚拉高：这样既可使 GPIO 正常工作，同时不会产生太多功耗。

NVMe 固态硬盘引导

NVMe（非易失性快速存储器）是通过 PCIe 总线进行外部存储访问的标准。你可以通过计算模块 4（CM4）IO 板、树莓派 5 上的 PCIe 槽连接 NVMe 驱动器。再通过一些额外配置，你就可以从 NVMe 驱动器启动了。

准备工作

硬件

• NVMe M.2 固态硬盘

• 一款 PCIe 转标准 M.2 的转接器

  • 对于树莓派 5，我们推荐使用 M.2 HAT+，它能把树莓派的 PCIe FFC 槽转换为 M 键（Key）接口。

  • 对于 CM4，可搜索“PCIe 3.0 ×1 转 M.2 NGFF M 键 SSD NVMe PCIe 转接器”

要检查你的 NVMe 驱动器是否正确连接，请从其他存储设备（如存储卡）引导你的树莓派，并运行 ls -l /dev/nvme*。示例输出如下所示。

crw------- 1 root root 245, 0 Mar  9 14:58 /dev/nvme0
brw-rw---- 1 root disk 259, 0 Mar  9 14:58 /dev/nvme0n1

软件

运行以下命令可查看你正在运行的固件版本：

$ sudo rpi-eeprom-update

对于树莓派 5，你需要使用 2023 年 12 月 6 日及之后发布的固件。

为了 CM4，NVMe 引导支持于 2021 年 7 月引入。你需要自那时起发布的以下版本的软件：

• 引导加载程序

• VideoCore 固件

• 树莓派系统 Linux 内核

最新的树莓派系统发布包含你所需的一切。使用树莓派镜像制作工具可将树莓派系统镜像安装到你的驱动器上。

编辑 EEPROM 启动顺序

对于树莓派 5，你需要启动树莓派系统以编辑启动顺序。你可以从存储卡或 USB 驱动器启动树莓派来完成此步骤。即使更改启动设备，EEPROM 配置也会持久保留，因为 EEPROM 配置存储在板上本身。

使用树莓派配置命令行界面来更新启动加载程序：

$ sudo raspi-config

在 Advanced Options > Bootloader Version 下，选择 Latest。然后，单击 Finish 或按 Escape 键 可退出 raspi-config。

运行以下命令可将固件更新至最新版本：

$ sudo rpi-eeprom-update -a

然后，使用 sudo reboot 重启。你的树莓派 5 应该会从 NVMe 启动。

对于 CM4，请使用 rpiboot 更新引导加载程序。你可以在 USB 启动 GitHub 存储库中找到构建 rpiboot 并配置 IO 板切换 ROM 到 usbboot 模式的说明。

对于搭载了 eMMC 的 CM4 版本，请确保你已将 NVMe 设置为引导顺序中的第一项。请记住在 recovery/boot.conf 中将 NVMe 引导模式 6 添加到 BOOT_ORDER 中。

当 SD 卡插槽为空时，CM4 Lite 会自动从 NVMe 引导。

NVMe BOOT_ORDER

EEPROM 配置中的 BOOT_ORDER 设置控制引导行为。对于 NVMe 引导，请使用引导模式 6。有关更多信息，请参见树莓派引导加载程序配置。

例子

以下是引导加载程序检测到 NVMe 驱动器时的串口输出示例：

Boot mode: SD (01) order f64
Boot mode: USB-MSD (04) order f6
Boot mode: NVME (06) order f
VID 0x144d MN Samsung SSD 970 EVO Plus 250GB
NVME on

然后它将找到一个 FAT 分区并加载 start4.elf ：

Read start4.elf bytes  2937840 hnd 0x00050287 hash ''

然后加载内核并引导操作系统：

MESS:00:00:07.096119:0: brfs: File read: /mfs/sd/kernel8.img
MESS:00:00:07.098682:0: Loading 'kernel8.img' to 0x80000 size 0x1441a00
MESS:00:00:07.146055:0:[   0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd083]

在 Linux 中，SSD 显示为 /dev/nvme0，而在“namespace(命名空间）”中显示为 /dev/nvme0n1。将会有两个分区 /dev/nvme0n1p1 （FAT）和 /dev/nvme0n1p2 （EXT4）。使用 lsblk 来检查分区分配：

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
nvme0n1     259:0    0 232.9G  0 disk
├─nvme0n1p1 259:1    0   256M  0 part /boot/firmware
└─nvme0n1p2 259:2    0 232.6G  0 part /

故障排除

如果引导过程失败，请在 GitHub 存储库 rpi-eeprom 上提交问题，确保附上控制台输出以及引导过程中所有屏幕显示的内容。

HTTP 引导

网络安装功能使用以太网上的 HTTP 引导树莓派进入嵌入式树莓派启动盘制作工具。

除了网络安装，你还可能用 HTTP 下载的文件显式引导设备启动，即使禁用引导，网络安装也能用。

例如，你可以将这添加到你的 BOOT_ORDER 作为备用引导方法，或者将其放在 GPIO 条件后，在 GPIO 引脚拉低时从你自己的服务器启动 HTTP 引导。

例如，如果将以下内容添加到你的 EEPROM 配置中，且 GPIO 8（默认状态为 1 或高电平）被拉低，将下载文件 http://downloads.raspberrypi.org:80/net_install/boot.img、http://downloads.raspberrypi.org:80/net_install/boot.sig。如果启用开机网络安装，则会使用相同的网址。如果 GPIO 8 未被拉低，则行为将保持不变。

[gpio8=0]
BOOT_ORDER=0xf7
HTTP_HOST=downloads.raspberrypi.org
NET_INSTALL_ENABLED=0

boot.img 和签名文件 boot.sig 是个包含引导文件系统的内存盘。详情请参阅 boot_ramdisk。

如果启用安全启动并且未设置 HTTP_HOST，则将忽略 BOOT_ORDER 中的 HTTP。

要求

要使用 HTTP 引导，请更新至 2022 年 3 月 10 日和后续版本的引导程序。HTTP 引导需要有线以太网连接。

要使用定制 CA 证书，请更新至 2024 年 4 月 5 日和后续版本的引导程序。只有运行 BCM2712 CPU 的设备支持才定制 CA 证书。

键

所有 HTTP 下载必须签名。引导加载程序包含一个用于默认主机 fw-download-alias1.raspberrypi.com 上文件的公钥。除非设置了 HTTP_HOST，并在 EEPROM 中内置公钥，否则该密钥将用于验证网络安装镜像。这能让你在自己的服务器上托管树莓派网络安装镜像。

警告

使用你自己的网络安装镜像将需要你对镜像进行签名，并将你的公钥添加到 EEPROM。如果你后续进行了公版 EEPROM 更新，你的密钥将丢失，并且需要重新添加。

USBBOOT 包含了编程公钥所需的全部工具。

使用以下命令将你的公钥添加到 EEPROM。boot.conf 包含你的修改：

$ rpi-eeprom-config -c boot.conf -p mypubkey.pem -o pieeprom.upd pieeprom.original.bin

使用以下命令可为你的 EEPROM 生成签名：

$ rpi-eeprom-digest -i pieeprom.upd -o pieeprom.sig

然后，使用以下命令使用你的私钥对网络安装镜像进行签名：

$ rpi-eeprom-digest -i boot.img -o boot.sig -k myprivkey.pem

最后，将 boot.img 和 boot.sig 放在你的网络服务器上，以使用自己签名的网络安装镜像。

证书

为了安全起见，网络安装使用 HTTPS 从树莓派网站下载操作系统镜像。此功能使用我们在引导程序中内置的自有 CA 根证书来验证主机。

你可以将你自己的定制 CA 证书添加到设备的 EEPROM，以安全地从你自己的网站下载镜像。使用工具 rpi-eeprom-config 的参数 --cacertder 能添加 DER 编码的证书。你必须在 EEPROM 配置设置中放置证书的哈希值，以确保证书未经篡改。

运行以下命令生成 DER 编码的证书：

$ openssl x509 -in your_ca_root_cert.pem -out cert.der -outform DER

然后，运行以下命令生成证书的 SHA-256 哈希：

$ sha256sum cert.der

应该会看到类似如下输出：

701bd97f67b0f5483a9734e6e5cf72f9a123407b346088638f597878563193fc  cert.der

接下来，更新 boot.conf 以包含证书的哈希值：

$ sudo rpi-eeprom-config --edit

在 [gpio8=0] 部分配置以下设置，替换为：

• 将 <你的网站> 替换为你的网站，例如 yourserver.org

• 将 <文件路径> 替换为托管在你的网站上的操作系统镜像的路径，例如 path/to/files

• 使用上面生成的哈希值 701bd97f67b0f5483a9734e6e5cf72f9a123407b346088638f597878563193fc，例如 <哈希值>

[all]
BOOT_UART=1
POWER_OFF_ON_HALT=0
BOOT_ORDER=0xf461

[gpio8=0]
BOOT_ORDER=0xf7
NET_INSTALL_ENABLED=0
HTTP_HOST=<你的网站>
HTTP_PATH=<文件路径>
HTTP_CACERT_HASH=<哈希值>

当你指定 HTTP_CACERT_HASH 时，网络安装将通过 HTTPS 下载镜像。没有哈希时，网络安装将使用 HTTP 下载镜像。

最后，使用以下命令将所有内容加载到 EEPROM 中：

$ rpi-eeprom-config -c boot.conf -p mypubkey.pem -o pieeprom.bin --cacertder cert.der pieeprom.original.bin
$ rpi-eeprom-digest -k myprivkey.pem -i pieeprom.bin -o pieeprom.sig

在网络启动过程中，你的树莓派应该使用 HTTPS 而非 HTTP。要查看由网络安装解析的完整的 HTTPS 下载链接，请查看引导输出：

Loading boot.img ...
HTTP: GET request for https://yourserver.org:443/path/to/files/boot.sig
HTTP: GET request for https://yourserver.org:443/path/to/files/boot.img

安全启动

如果启用了安全启动，则树莓派只能运行由客户私钥签名的代码。因此，如果你想要在安全启动的情况下使用网络安装、HTTP 启动模式，你必须使用自己的密钥签署 boot.img 并生成 boot.sig，并在某处托管这些文件供下载。EEPROM 中的公钥将用于验证镜像。

如果启用安全启动且未设置 HTTP_HOST，则网络安装和 HTTP 引导将被禁用。

有关安全启动的更多信息，请参阅 USBBOOT。

引导顺序

重要

此启动顺序仅适用于基于 BCM2837、BCM2837B0 的树莓派。在此之前的型号，树莓派将尝试存储卡引导，然后是 USB 设备模式引导。有关树莓派 4 和树莓派 5 的引导顺序，请参阅 EEPROM 引导流程部分。

树莓派 3 上的 USB 引导默认取决于所使用的版本。如果默认未启用 USB 引导模式，请参阅此页面获取有关启用 USB 引导模式的信息。

当 BCM2837 引导时，它使用两个不同的来源来确定要启用哪些引导模式。首先，会检查一次性可编程（OTP）存储器块，看哪些引导模式已启用。如果启用了 GPIO 引导模式设置，则会测试相关的 GPIO 线，以选择应尝试哪个已在 OTP 中启用的引导模式。请注意，GPIO 引导模式仅可用于选择已在 OTP 中启用的引导模式。有关配置 GPIO 引导模式的详细信息，请参阅 GPIO 引导模式。在默认情况下，GPIO 引导模式已禁用。

接下来，启动 ROM 会在每个启动源中检查名为bootcode.bin的文件；如果找到，它会将代码加载到本地 128K 缓存并跳转到该代码。总体启动模式过程如下：

• BCM2837 启动

• 读取 OTP 以确定启用哪些启动模式

• 如果启用了 GPIO 启动模式，请使用 GPIO 启动模式来细化启用的启动模式列表

• 如果启用：检查 GPIO 48-53 上的主 SD 是否存在 bootcode.bin

  • 成功 - 启动

  • 失败 - 超时（五秒）

• 如果启用：检查辅助 SD

  • 成功 - 启动

  • 失败 - 超时（五秒）

• 如果启用：检查 NAND

• 如果启用：检查 SPI

• 如果启用：检查 USB

  • 如果 OTG 引脚 == 0

    • 启用 USB，等待有效的 USB 2.0 设备（2 秒）

      • 设备已找到：

        • 如果设备类型 == hub

          • 递归每个设备

        • 如果设备类型 == (大容量存储或 LAN951x)

          • 存储在设备列表中

    • 递归遍历每个大容量存储设备

      • 如果找到 bootcode.bin 引导

    • 递归遍历每个 LAN951x

      • DHCP / TFTP 引导

  • 其他（设备模式启动）

    • 启用设备模式，等待主机 PC 枚举

    • 我们用 VID: 0a5c PID: 0x2763 回复 PC（树莓派 1、树莓派 2）或 0x2764 （树莓派 3）

注意

如果没有插入存储卡，SD 引导模式将在 5 秒钟后失败。为了缩短这个时间并更快地切换到 USB 模式，你可以插入空白的存储卡，或者使用上面描述的 GPIO 引导模式 OTP 设置，仅启用 USB。GPIO 的默认拉取在 ARM 外围设备数据手册的第 102 页上有定义。如果引导时的值不等于默认拉取值，则启用该引导模式。USB 枚举是一种使下游设备在集线器上获取电源，然后等待设备拉动 D+ 和 D- 线以指示其是 USB 1 还是 USB 2 的方法。这可能需要一段时间：对于某些设备，硬盘驱动器可能需要长达 3 秒的时间来启动并开始枚举过程。因为这是唯一能检测硬件连接的方法，所以我们必须等待的最短时间为两秒。如果设备在最大超时时间后仍未响应，则可以使用 program_usb_boot_timeout=1 在 config.txt 中增加超时时间至五秒。大容量存储引导优先于以太网引导。不再需要第一个分区是 FAT 分区，因为大容量存储引导将继续搜索第一个分区之外的 FAT 分区。引导 ROM 现在还支持 GUID 分区，并已测试过使用 Mac、Windows 和 Linux 分区的硬盘。使用供应商 ID 0x0424 和产品 ID 0xec00 可以检测 LAN951x，这与独立的 LAN9500 设备不同，后者的产品 ID 是 0x9500/0x9e00。要使用独立的 LAN9500，需要添加 I²C EEPROM 以更改这些 ID 以匹配 LAN951x。

主要存储卡引导模式默认设置为 GPIO 49-53。可以在第二组引脚上从次要存储卡引导，即将次要存储卡连接到 GPIO 引脚。但是，我们尚未启用此功能。

NAND 引导和 SPI 引导模式的确能用，尽管它们还未完全支持 GPU。

USB 设备引导模式在出厂时默认启用，但 USB 主机引导模式只有在 program_usb_boot_mode=1 时才启用。一旦启用，处理器将使用处理器上的 OTGID 引脚的值来在这两种模式之间做出决定。在所有树莓派 B/B+ 上，OTGID 引脚被驱动为 0，因此一旦启用，就只能通过主机模式引导（无法再使用设备模式引导，因为 LAN951x 设备阻挡了路径）。

如果将 OTGID 引脚浮置（例如，插入 PC），则树莓派 Zero 或计算模块将作为 USB 设备引导启动，因此你可以将 bootcode.bin 推入设备中。相关 usbboot 代码可在 GitHub 上找到。

EEPROM 引导流程

自树莓派 4 起，树莓派 旗舰设备使用 EEPROM 启动加载程序。与以前的产品相比，主要区别在于第二阶段启动加载程序是从 SPI 闪存 EEPROM 加载，而不是像以前的产品一样从 bootcode.bin 文件加载。

第一阶段启动加载程序

ROM（第一阶段）的引导流程如下：

• SoC 上电

• 读取 OTP（一次性可编程存储器）以确定是否配置了 nRPIBOOT GPIO

• 如果 nRPIBOOT GPIO 为高电平或 OTP 未定义 nRPIBOOT GPIO

  • 检查 OTP 以查看是否可以从 SD/EMMC 加载 recovery.bin

    • 如果启用了 SD recovery.bin，则检查主 SD/EMMC 中的 recovery.bin

      • 成功：运行 recovery.bin 并更新 SPI EEPROM

      • 失败：继续

  • 检查 SPI EEPROM 中的第二阶段加载程序

    • 成功：运行第二阶段启动加载程序

    • 失败：继续

• 如果成功

  • 尝试从 USB 设备启动 加载 recovery.bin

    • 成功：运行 recovery.bin 并更新 SPI EEPROM 或切换到 USB 大容量存储设备模式

    • 失败：重试 USB 设备启动

注意

recovery.bin 是一款用于更新引导加载程序 SPI EEPROM 镜像的最小第二阶段程序。

第二阶段引导程序

本节介绍了第二阶段引导程序的高级流程。

请参阅引导程序配置 页面以获取有关每种引导模式的更多信息，以及引导文件夹 页面以了解此阶段加载的 GPU 固件文件的描述。

• 初始化时钟和 SDRAM

• 读取 EEPROM 配置文件

• 检查 PM_RSTS 寄存器以确定是否请求 HALT

  • 检查 POWER_OFF_ON_HALT 和 WAKE_ON_GPIO 的 EEPROM 配置设置

  • 如果 POWER_OFF_ON_HALT 为 1 且 WAKE_ON_GPIO 为 0，则

    • 使用电源管理芯片（PMIC）关闭系统电源

  • 否则，如果 WAKE_ON_GPIO 为 1，则

    • 启用 GPIO3 的下降沿中断以便在 GPIO3 被拉低时唤醒

  • 进入休眠

• 当为 True（真）

  • 从 EEPROM 配置文件中的 BOOT_ORDER 参数读取下一个引导模式

  • 如果引导模式为 RESTART，则

    • 跳回到 BOOT_ORDER 字段中的第一个引导模式

  • 否则如果引导模式为 STOP，则

    • 显示 start.elf 未找到的错误模式 并永久等待。

  • 否则如果引导模式为 SD CARD，则

    • 尝试从存储卡加载固件

      • 成功：运行固件

      • 失败：继续

  • 否则如果引导模式为 NETWORK，则

    • 使用 DHCP 协议请求 IP 地址

    • 从 DHCP 或静态定义的 TFTP 服务器加载固件

    • 如果未找到固件或发生超时或网络错误，则继续

  • 否则如果引导模式为 USB-MSD 或引导模式为 BCM-USB-MSD，则

    • 当 USB 发现未超时时

      • 检查 USB 大容量存储设备

      • 如果找到新的大容量存储设备，则

        • 对每个驱动器（LUN）

          • 尝试加载固件

            • 成功：运行固件

            • 失败：前进到下一个驱动器（LUN）

  • 否则如果引导模式为NVME，则

    • 扫描 PCIe 以查找 NVMe 设备，如果找到

      • 尝试从 NVMe 设备加载固件

        • 成功：运行固件

        • 失败：继续

  • 否则如果引导模式为 RPIBOOT，则

    • 尝试使用 USB 设备模式从 USB OTG 端口加载固件 ——参见USB 引导。RPIBOOT模式没有超时。

树莓派 5 的不同

• 电源按钮用于从 PMIC STANDBY、HALT 唤醒，而非 GPIO 3。

• 固件加载 start.elf 而不是 start.elf。实际上，引导加载程序内置了嵌入版本的 start.elf。

• 连接到 3A 电源时，默认禁用 USB 启动。在 /boot/firmware/config.txt 中设置 usb_max_current_enable=1 可启用 USB 启动。或者你可以在 USB 启动失败时，按一下电源按钮来临时启用 usb_max_current_enable 并继续引导。但是，如果是按电源按钮启用的，该设置在重启后将失效。

引导加载程序更新

如果找到 pieeprom.upd 文件，固件启动之前也可以更新引导加载程序。有关引导加载程序更新的更多信息，请参阅引导加载程序 EEPROM 页面。

安全模式操作系统更新（tryboot ）

引导加载程序/固件提供了一个一次性标志，如果设置了该标志，会清除，但会导致加载 tryboot.txt 而不是 config.txt。这种备用配置将指定待处理的操作系统更新固件、cmdline、内核和 os_prefix 参数。因为在启动固件之前清除了该标志，所以崩溃或重置会导致在下次重启时加载原始的 config.txt 文件。

要设置 tryboot 标志，请在 reboot 命令中的分区号后添加 tryboot。通常，分区号默认为 0。但如果要添加额外的参数，则必须指定分区号。传递参数给 reboot 时始终使用引号：它只接受一个参数：

$ sudo reboot '0 tryboot'

所有树莓派型号都支持 tryboot，但是在树莓派 4 A 1.0 版本和 1.1 版本上，EEPROM 不能被写保护。这是因为旧款树莓派 4B 设备必须重置电源供应（会丢失 tryboot 状态），而这些信息正存储在 EEPROM。

若启用安全启动，则 tryboot 模式将导致加载 tryboot.img 而不是 boot.img。

tryboot_a_b 模式

如果 autoboot.txt 中的 tryboot_a_b 属性设置为 1，则加载的是 config.txt 而不是 tryboot.txt。这是因为在更高级别（分区）已经进行了 tryboot 切换，因此在备用分区本身内部不需要具有 tryboot.txt 文件。

当从内置的 boot.img 镜像加载文件，tryboot_a_b 属性会被隐式设置为 1。

树莓派引导加载程序配置

编辑配置

在编辑引导加载程序配置之前，请更新你的系统以获取 rpi-eeprom 软件包的最新版本。

要查看当前的 EEPROM 配置，请运行以下命令：

$ rpi-eeprom-config

要编辑当前的 EEPROM 配置并将更新应用于最新的 EEPROM 版本，请运行以下命令：

$ sudo -E rpi-eeprom-config --edit

关于 EEPROM 更新过程的更多信息，请参阅启动 EEPROM。

配置属性

本节描述引导加载程序中所有可用的配置项。语法与 config.txt 相同，但属性是特定于引导加载程序的。条件过滤器也受支持，除了 EDID 之外。

BOOT_UART

如果 1 则启用 GPIO 14 和 15 上的 UART 调试输出。将接收调试终端配置为 115200bps，8 位，无奇偶校验位，1 个停止位。

默认: 0

UART_BAUD

仅适用于树莓派 5。

更改引导加载程序 UART 的波特率。

支持的值: 9600、19200、38400、57600、115200、230400、460800、921600

默认: 115200

WAKE_ON_GPIO

若为 1 则 sudo halt 将在较低功耗模式下运行，直到 GPIO3 或 GLOBAL_EN 短接至地。

在树莓派 5 上，此设置并不相关，因为专用电源按钮可以始终用于唤醒来自 HALT 或 STANDBY。

默认: 1

POWER_OFF_ON_HALT

如果 1 和 WAKE_ON_GPIO=0，那么 sudo halt 将关闭所有电源管理芯片（PMIC）输出。这是 halt 的最低功耗状态，但可能会导致某些扩展板出现问题，因为 5V 仍将处于开启状态。GLOBAL_EN 必须短接地来启动。

树莓派 400 有一个专用的电源按钮，即使处理器关闭也能工作。这个功能默认启用，但可设置 WAKE_ON_GPIO=2 来使用外部 GPIO 电源按钮，而不是专用电源按钮。

在树莓派 5 上，这将把 PMIC 置于 STANDBY 模式，其中所有输出都被关闭。无需设置 WAKE_ON_GPIO，按下专用电源按钮将启动设备。

默认: 0

BOOT_ORDER

BOOT_ORDER 设置能对不同启动模式的优先级进行灵活配置。它表示为一个 32 位无符号整数，其中每个半 B 代表一个启动模式。启动模式按照从最低有效半 B 到最高有效半 B 的顺序尝试。

BOOT_ORDER 字段

BOOT_ORDER 属性定义了不同引导模式的顺序。它是从右到左读取的，最多可以定义八位数字。

RPIBOOT 与计算模块 4 同时使用，加载自定义调试镜像（例如，Linux RAM-disk）而不是正常的引导。这应该是最后的引导选项，因为它目前不支持超时或重试。

BOOT_ORDER 示例

MAX_RESTARTS

如果遇到 0xf 重启 ( RESTART ) 引导模式超过 MAX_RESTARTS 次数，则会触发看门狗复位。不建议一般使用这个，但在需要完全重置以解决硬件/网络接口故障的测试和远程系统上可能会有用。

默认值： -1 (无限)

SD_BOOT_MAX_RETRIES

在移动到由 BOOT_ORDER 定义的下一个引导模式之前，在 SD 引导失败后重试的次数。

-1 意味着无限重试。

默认值: 0

NET_BOOT_MAX_RETRIES

失败后在移动到下一个由 BOOT_ORDER 定义的引导模式之前，网络引导将重试的次数。

-1 表示无限重试。

默认： 0

DHCP_TIMEOUT

整个 DHCP 序列在失败当前迭代之前的超时时间（毫秒）。

最小值: 5000

默认值: 45000

DHCP_REQ_TIMEOUT

DHCP DISCOVER 或 DHCP REQ 重试之前的超时时间（毫秒）。

最小值: 500

默认值: 4000

TFTP_FILE_TIMEOUT

通过 TFTP 单个文件下载的超时时间（毫秒）。

最小值: 5000

默认值: 30000

TFTP_IP

可选的点分十进制 IP 地址（例如 192.168.1.99）用于 TFTP 服务器，覆盖来自 DHCP 请求的服务器 IP。

在家庭网络上，可能会发现这很有用，因为可以使用 tftpd-hpa 代替 dnsmasq，其中宽带路由器是 DHCP 服务器。

默认： ""

TFTP_PREFIX

为了让每个树莓派都有唯一 TFTP 启动目录，引导加载程序会将文件名前缀添加到特定于设备的目录。如果在带前缀的目录中找不到 start4.elf/start.elf，则会清除前缀。

在早期型号上，序列号被用作前缀，但在树莓派 4 和 5 上，MAC 地址不再由序列号生成，这使得通过检查 DHCPDISCOVER 包自动创建 tftpboot 目录在服务器上变得困难。为了方便，TFTP_PREFIX 可以定义为 MAC 地址、固定值或序列号（默认）。

默认值: 0

TFTP_PREFIX_STR

当 TFTP_PREFIX 设置为 1 时，指定用于自定义目录前缀的字符串。例如：TFTP_PREFIX_STR=tftp_test/

默认值: ""

最大长度：32 个字符

PXE_OPTION43

使用不同的字符串覆盖 PXE Option43 匹配字符串。通常最好将定制应用于 DHCP 服务器，而不是更改客户端行为，但在无法进行更改的情况下提供此选项。

默认：Raspberry Pi Boot

DHCP_OPTION97

在之前的版本中，客户端 GUID（Option97）只是将序列号重复四次。默认情况下，新的 GUID 格式为四字符码（FourCC）的串联（RPi4 0x34695052 适用于 树莓派 4 或 RPi5 0x35695052 适用于树莓派 5），板子版本（例如 0x00c03111、0x00d04170）（4 B），MAC 地址的最低有效 4 B 以及 4 B 的序列号。这旨在是独一无二的，同时也向 DHCP 服务器提供结构化信息，使得可以识别树莓派 4 和 5 计算机，而无需依赖以太网 MAC OUID。

指定 DHCP_OPTION97=0 可恢复旧行为，或指定非零十六进制值以指定自定义的 4 字节前缀。

默认值： 0x34695052

MAC_ADDRESS

用给定的值覆盖树莓派以太网 MAC 地址。例如 dc:a6:32:01:36:c2

默认： ""

MAC_ADDRESS_OTP

使用存储在客户 OTP 寄存器中的值覆盖树莓派以太网 MAC 地址。

例如，要使用存储在 Customer OTP 的行 0 和 1 中的 MAC 地址。

MAC_ADDRESS_OTP=0,1

第一个值（例如中的第 0 行）包含 OUI 和 MAC 地址的最高 8 位。第二个值（例如中的第 1 行）存储 MAC 地址的剩余 16 位。这与在制造时用于树莓派 MAC 地址的格式相同。

可以选择并以任意顺序组合任意两个客户行。

Customer OTP 行是 OTP 寄存器 36 到 43，在 vcgencmd otp_dump 输出中，所以如果前两行被编程如下，则 MAC_ADDRESS_OTP=0,1 就会给出一个 MAC 地址为 e4:5f:01:20:24:7e。

36:247e0000
37:e45f0120

默认值： ""

静态 IP 地址配置

如果设置了 TFTP_IP 和以下选项，则跳过 DHCP，并应用静态 IP 配置。如果 TFTP 服务器与客户端在同一子网上，则可省略网关（GATEWAY）。

CLIENT_IP

客户端的 IP 地址，例如 192.168.0.32

默认： ""

SUBNET

子网地址掩码，例如 255.255.255.0

默认： ""

GATEWAY

如果 TFTP 服务器位于不同子网上，则要使用的网关地址，例如 192.168.0.1

默认： ""

DISABLE_HDMI

如果 DISABLE_HDMI=1，HDMI 启动诊断显示将被禁用。其他非零值保留供将来使用。

默认： 0

HDMI_DELAY

跳过 HDMI 诊断显示，最多 N 秒（默认值 5）,除非发生致命错误。默认行为旨在避免在正常 SD/USB 引导时，引导加载程序诊断屏幕短暂出现。

默认: 5

ENABLE_SELF_UPDATE

启用引导加载程序从 TFTP/USB 大容量存储设备（MSD）引导文件系统中更新自身。

如果自更新已启用，则引导加载程序将在引导文件系统中查找更新文件（.sig/.upd）。如果更新镜像与当前镜像不同，则应用更新并重置系统。否则，如果 EEPROM 镜像是逐字节相同的，则引导将继续正常进行。

注：

• 2021 年之前的引导加载程序版本不支持 self-update。

• 2022 年之前，SD 启动中未启用自更新功能。在树莓派 4 上，ROM 已经可以从存储卡加载 recovery.bin。在 CM4 上，自更新和 recovery.bin 均不生效，需要使用 USB 启动（请参阅计算模块 EEPROM 引导程序文档）。

• 从 2022 年开始（beta 和稳定版），可以启用存储卡的自更新功能。

• 对于网络启动，请确保 TFTP 的 boot 目录可以通过 NFS 挂载，并且 rpi-eeprom-update 可以写入其中。

默认值: 1

FREEZE_VERSION

以前，此属性仅由 rpi-eeprom-update 脚本检查。但是，现在自更新已启用，引导加载程序还将检查此属性。如果设置为 1，则将覆盖 ENABLE_SELF_UPDATE 以停止自动更新。要禁用 FREEZE_VERSION，你必须使用带有 recovery.bin 的存储卡引导。

自定义 EEPROM 更新脚本也必须检查此标志。

默认： 0

HTTP_HOST

如果启动网络安装或 HTTP 引导，则会从此服务器下载 boot.img 和 boot.sig。

无效的主机名将被忽略。它们应仅包含小写字母数字字符和 - 或 .。如果设置了 HTTP_HOST，则将禁用 HTTPS 并改用普通的 HTTP。你可以指定 IP 地址以避免 DNS 查找的需要。在主机名中不要包含 HTTP 方案及正斜杠。

默认: fw-download-alias1.raspberrypi.com

HTTP_PORT

你可以使用此属性来更改用于网络安装和 HTTP 引导的端口。当使用默认主机 fw-download-alias1.raspberrypi.com 时，启用 HTTPS。如果更改了 HTTP_HOST，则禁用 HTTPS 并使用普通 HTTP。

当禁用 HTTPS 时，即使将 HTTP_PORT 更改为 443，仍将使用普通 HTTP。

默认值：如果启用 HTTPS，则为443，否则为80

HTTP_PATH

用于网络安装和 HTTP 引导的路径。

区分大小写。路径分隔符使用正斜杠（Linux 样式）。前导和尾部的正斜杠不是必需的。

如果未设置 HTTP_HOST，则忽略 HTTP_PATH，URL 将为 https://fw-download-alias1.raspberrypi.com:443/net_install/boot.img。如果设置了 HTTP_HOST，URL 将为 http://<HTTP_HOST>:<HTTP_PORT>/<HTTP_PATH>/boot.img

默认值：net_install

IMAGER_REPO_URL

嵌入式树莓派制造者应用程序会在启动时下载一个 JSON 文件进行配置。

你可以更改内嵌的树莓派制作程序应用程序使用的 JSON 文件的网址，以便提供你自己的镜像。你可以通过参数 --repo 传递网址来测试标准的 树莓派 制作程序应用程序。

默认： http://downloads.raspberrypi.org/os_list_imagingutility_v3.json

NET_INSTALL_ENABLED

当启用网络安装时，如果检测到了键盘，引导加载程序会在启动时显示网络安装界面。

为了启用网络安装，请添加 NET_INSTALL_ENABLED=1，或者为了禁用网络安装，请添加 NET_INSTALL_ENABLED=0。

如果设置 DISABLE_HDMI=1，则此设置将被忽略，网络安装将被禁用。

为了检测键盘，网络安装必须初始化 USB 控制器并枚举设备。这会增加约 1 秒的启动时间，因此在某些嵌入式应用中禁用网络安装可能更为有利。

在树莓派 4 和树莓派 400 上默认为 1，在计算模块 4 上为 0。

NET_INSTALL_KEYBOARD_WAIT

如果启用了网络安装，则引导加载程序会尝试检测键盘和按 SHIFT 键以启动网络安装。你可以使用此属性更改此等待时间的长度（以毫秒为单位）。

将此设置为 0 将禁用对键盘的等待，尽管如果找不到引导文件且 USB 引导模式为 4 且处于 BOOT_ORDER 中，则仍可以启动网络安装。

注意

测试表明检测键盘和 SHIFT 至少需要 750 毫秒。

默认: 900

NETCONSOLE - 高级日志记录

NETCONSOLE 复制调试消息到网络接口。IP 地址和接口由 NETCONSOLE 字符串定义。

注意

NETCONSOLE 阻塞，直到以太网连接建立或超时发生。超时值为 DHCP_TIMEOUT，尽管除非请求网络引导，否则不会尝试 DHCP。

格式

有关更多信息，请参阅 Netconsole 文档。

src_port@src_ip/dev_name,dst_port@dst_ip/dst_mac
E.g. 6665@169.254.1.1/,6666@/

为了简化解析，引导加载程序要求每个字段分隔符都存在。必须指定源 IP 地址，但以下字段可以留空并分配默认值。

• src_port - 6665

• dev_name - "" (设备名称始终被忽略)

• dst_port - 6666

• dst_ip - 255.255.255.255

• dst_mac - 00:00:00:00:00

通过将测试树莓派 4 连接到运行 WireShark 的另一个树莓派，并选择“udp.srcport == 6665”作为过滤器，然后选择 分析 → 跟随 → UDP 数据流 以 ASCII 日志形式查看数据的一种方式。

默认情况下不应启用 NETCONSOLE，因为这可能会导致网络问题。可以通过 GPIO 过滤器按需启用。

# Enable debug if GPIO 7 is pulled low
[gpio7=0]
NETCONSOLE=6665@169.254.1.1/,6666@/

默认: "" (未启用)

最大长度: 32 个字符

PARTITION

如果未显式地由 reboot 命令 (例如 sudo reboot N) 或 boot_partition=N 在 autoboot.txt 中设置，则可以使用 PARTITION 选项来指定引导分区号。用户可以按下按钮来从救援分区启动。

# Boot from partition 2 if GPIO 7 is pulled low
[gpio7=0]
PARTITION=2

默认值: 0

PSU_MAX_CURRENT

仅适用于树莓派 5。

如果设置，该参数指示固件跳过 USB 供电握手，并假定连接到了具有给定电流等级的电源。通常设置为 3000（小电流电源） 或 5000（大电流电源）。

默认: ""

USB_MSD_EXCLUDE_VID_PID

一个包含最多四个 VID/PID 对的列表，指定引导加载程序应忽略的设备。如果这与 HUB 匹配，则该 HUB 不会被枚举，导致所有下游设备被排除。这旨在允许在引导枚举期间忽略有问题的设备（例如，枚举速度非常慢）。这是引导加载程序特有的，并不传递给操作系统。

格式是一个以 VID 为最高有效半字节的十六进制值的逗号分隔列表。不允许有空格。例如 034700a0,a4231234

默认值： ""

USB_MSD_DISCOVER_TIMEOUT

如果在此超时期间未找到 USB 大容量存储设备，则停止 USB-MSD 并选择下一个引导模式。

最小值： 5000 （5 秒）

默认: 20000 (20 秒)

USB_MSD_LUN_TIMEOUT

在前进到下一个 LUN 之前等待的毫秒数，例如多槽 SD-CARD 读卡器。这仍在调整中，但可能有助于加快启动速度，如果连接了旧、慢设备以及包含 OS 的快速 USB-MSD 设备。

最小值: 100

默认: 2000 (2 秒)

USB_MSD_PWR_OFF_TIME

仅适用于树莓派 4。

在树莓派重启时，硬件会关闭 USB 电源。短暂的断电时间可能会导致某些 USB 设备出现问题，因此可以使用此参数强制执行较长的断电时间，就像在物理上拔掉电线一样。

在树莓派 4 版本 1.3 及更早版本上，要配置长关机需要启用 XHCI 控制器，因此实际上会先进行短关机，然后是较长的可配置关机。通过将此参数设置为 0，可以跳过较长的可配置关机。

在更新的版本中，硬件会确保 USB 电源在重启后关闭，引导加载程序仅在此经过超时后才启用电源。这是在内存初始化后发生的，确保 USB 电源至少被断开 2 秒。因此，此参数一般对新的硬件版本没有影响。

最小值： 0

最大值: 5000

默认值: 1000 (1 秒)

USB_MSD_STARTUP_DELAY

如果定义了，那么在 USB 主控制器初始化后，延迟给定的超时时间进行 USB 枚举。如果 USB 硬盘驱动器需要很长时间初始化，随即触发 USB 超时，那么可以使用此延迟给驱动程序额外的初始化时间。可能还需要增加总体 USB 超时时间 ( USB_MSD_DISCOVER_TIMEOUT )。

最小值: 0

最大值: 30000 (30 秒)

默认值: 0

VL805

仅适用于计算模块 4。

如果 VL805 属性设置为 1，则引导加载程序将搜索 VL805 PCIe XHCI 控制器，并尝试使用嵌入在引导加载程序 EEPROM 中的 VL805 固件进行初始化。这使得工业设计可以使用 VL805 XHCI 控制器而无需提供专用的 SPI EEPROM 来存储 VL805 固件。

• 在计算模块 4 上，引导加载程序永远不会写入专用的 VL805 SPI EEPROM。此选项仅配置控制器从 SDRAM 加载固件。

• 如果 VL805 XHCI 控制器有专用的 EEPROM，请勿使用此选项。它将无法初始化，因为 VL805 ROM 将尝试使用专用的 SPI EEPROM（如果已安装）。

• 嵌入式 VL805 固件假定与树莓派 4B 相同的 USB 配置（两个 USB 3.0 端口和四个 USB 2.0 端口）。不支持加载替代的 VL805 固件镜像，应该改用专用的 VL805 SPI EEPROM 来替换这样的配置。

默认: 0

XHCI_DEBUG

此属性是一个位字段，用于控制 USB 调试消息在大容量存储引导模式下的冗长程度。启用所有这些消息会生成大量日志数据，会降低启动速度，甚至可能导致启动失败。对于详细日志，最好使用 NETCONSOLE。

要合并值，请将它们相加。例如：

# Enable mass storage and USB descriptor logging
XHCI_DEBUG=0x3

默认： 0x0 （未启用 USB 调试消息）

[config.txt] 部分

在读取 config.txt GPU 固件 start4.elf 后，读取引导加载程序 EEPROM 配置并检查是否存在名为 [config.txt] 的部分。如果 [config.txt] 部分存在，则将从此部分开头到文件末尾的内容附加到内存中，以便与从引导分区读取的 config.txt 文件的内容组合。这可用于自动应用设置到每个操作系统，例如 dtoverlays。

警告

如果你配置引导加载程序时出现无法引导的无效配置，则必须重新刷新引导加载程序 EEPROM 为有效配置以引导。

技巧

一些配置属性存储在 config.txt 中。有关这些属性的更多信息，请参阅配置属性。

显示并行接口 (DPI)

在树莓派上使用 DPI 显示

在树莓派上使用 DPI 显示器

40 针通用输入/输出（GPIO）连接器可用于将显示并行接口（DPI）显示器连接到树莓派设备，作为使用专用显示串行接口（DSI）或高清多媒体接口（HDMI）的替代方案。

所有带有 40 针排针和计算模块的树莓派板都提供了高达 24 位并行 RGB 接口。此接口允许将并行 RGB 显示器连接到树莓派的 GPIO，无论是在 RGB24（每种红、绿和蓝色各 8 位）还是 RGB666（每种颜色 6 位）或 RGB565（5 位红色，6 位绿色和 5 位蓝色）模式下。

此接口由 GPU 固件控制，并可以通过用户通过特殊 config.txt 参数和启用正确的 Linux 设备树叠加层来进行编程。

GPIO 引脚

树莓派 GPIO 的 Bank 0 上可选择的一个替代功能是 DPI（显示并行接口），这是一个简单的时钟并行接口（最多可提供 R、G 和 B 的 8 位；时钟、使能、水平同步和垂直同步）。此接口在 GPIO Bank 0 上作为替代功能 2（ALT2）可用：

注意

DPI 输出引脚上的颜色值可以以 565、666 或 24 位模式显示（请参阅下表和参数 output_format 的 dpi_output_format 部分）的多种方式：

禁用其他 GPIO 外设

必须禁用使用冲突 GPIO 引脚的所有其他外设叠加层。在 config.txt 中，请注意注释/关闭所有已启用的 I²C/SPI dtparams：

dtparam=i2c_arm=off
dtparam=spi=off

配置显示器

内核模式设置（KMS）通用显示接口使输出能够接入任意显示器，只要你有合适的驱动程序。

自动检测

自动检测能让你的树莓派与显示器连接，而无需手动配置设备树叠加层。在默认情况下已启用自动检测。你可以通过将以下行添加到 config.txt 来启用显示器自动检测：

display_auto_detect=1

用 0 替换 1 可禁用自动检测。当你连接启用自动检测的官方树莓派显示器时，KMS 会自动确定显示器，配置适当的显示设置。

手动配置显示器

注意

在树莓派系统 Bookworm 及更高版本中，先前用于设置 DPI 的 dpi_output_format 和 dpi_timings 条目已被叠加层 vc4-kms-dpi-generic 取代。

要使用除树莓派官方显示屏之外的其他显示屏，必须在配置文件中指定 dtoverlay 条目。面板制造商应在 Linux 内核代码中配置你的显示屏的时序，并提供叠加层来启用这些设置。请参阅 Adafruit Kippah 显示屏条目获取示例。以下示例演示如何在你的 txt 文件中为 Kippah 显示屏设置 dtoverlay 条目：

dtoverlay=vc4-kms-kippah-7inch-overlay

显示是时序通常在内核中定义，但你也可以在提供的 BSD 驱动程序中定义它们。如果你的面板在内核代码中缺乏定义的叠加层，则可以使用 BSD 驱动程序将显示定时定义为参数。这使你能够为显示屏手动配置设备树条目。

以下示例演示如何使用设备树参数定义定时：

dtoverlay=vc4-kms-v3d
dtoverlay=vc4-kms-dpi-generic,hactive=480,hfp=26,hsync=16,hbp=10
dtparam=vactive=640,vfp=25,vsync=10,vbp=16
dtparam=clock-frequency=32000000,rgb666-padhi

注意

设备树行长度不得超过 80 个字符。当设置的行需要超过 80 个字符时，请将该参数的赋值拆分为多行。

参数显示树定义支持以下参数:

GPIO 和 40 脚排针

你可以在所有当前的树莓派主板上找到一个 40 脚 GPIO（通用输入/输出）排针。主板上所有的 GPIO 排针间距均为 0.1 英寸（2.54 mm）。

注意

有 “H”后缀的 Zero 和 Pico 不带排针。

通用 I/O (GPIO) 引脚可配置为通用输入、通用输出，或者最多六种特殊交替设置之一，其功能取决于引脚。

注意

GPIO 引脚编号方案不按数字顺序排列。GPIO 引脚 0 和 1 位于板上（物理引脚 27 和 28），但保留供高级用途。

输出

作为输出引脚指定的 GPIO 引脚可以设置为高电平（3.3V）/低电平（0V）。

输入

作为输入引脚指定的 GPIO 引脚可以读取为高电平（3.3V）/低电平（0V）。使用内部上拉/下拉电阻器可以更轻松地实现其功能。GPIO2 和 GPIO3 引脚内置上拉电阻器，但对于其他引脚，可以在软件中进行配置。

查看树莓派的 GPIO 引脚布局

可以通过打开终端窗口并运行命令 pinout 在树莓派上访问 GPIO 参考。此工具由 GPIO Zero Python 库提供，在树莓派系统中预装。

警告

尽管把简单的组件接入 GPIO 引脚是安全的，但要小心线路的连接方式。应该用电阻限制流经 LED 的电流。不要给 3.3V 的组件用 5V。不要把电机直连到 GPIO 引脚，应该使用 H 桥电路、电机控制板。

权限

为了使用 GPIO 接口，你的用户必须是 gpio 组的成员。默认用户账户已经如此，但对于其他用户，你须使用以下命令手动加入：

$ sudo usermod -a -G gpio <username>

GPIO 引脚

BCM2835 封装的 GPIO 在外设数据表中有时被称为“pads”，这是一个半导体设计术语，即“连接到外部世界的芯片”。

这些 pads 是可配置的 CMOS 推挽输出驱动器/输入缓冲器。可用于寄存器控制设置的包括：

• 内部上拉/下拉使能/失能

• 输出驱动强度

• 输入施密特触发器滤波

上电状态