配置
raspi-config
在 GitHub 上修改
raspi-config 可帮助您配置Raspberry Pi。对 raspi-config 的更改将修改 /boot/firmware/config.txt 和其他配置文件。
Getting started
要从桌面GUI打开配置工具，请转到 首选项 > 树莓派配置。
或者，运行以下命令通过终端访问配置工具：
$ sudo raspi-config|
Tip
|
一些高级配置在 raspi-config CLI中可用，但在Raspberry Pi配置GUI中不可用。
|
要从终端导航配置工具：
-
使用上下箭头键在设置列表中滚动。
-
使用 Right 或 Tab 访问
<Select>或<Finish>选项。 -
使用 Left 或 Tab 返回设置列表。
-
输入一个字母以按字母顺序跳转。例如，输入
E可以跳转到时区列表中的’Europe'。
Display options
VNC resolution
定义要在 headless 设置中使用的视频分辨率。
Interface options
启用和禁用各种物理和虚拟接口。
SSH
启用或禁用远程终端访问您的树莓派使用SSH。
SSH允许您从另一台计算机远程访问Raspberry Pi的命令行。SSH默认禁用。有关SSH的更多信息，请参阅 SSH documentation。
RPi Connect
启用或禁用 Raspberry Pi Connect，无需手动网络配置即可远程访问您的Raspberry Pi。
Performance options
Overclock
如果您的Raspberry Pi型号允许，请对CPU进行超频。即使在同一型号中，各个Raspberry Pi设备之间的超频潜力也会有所不同。超频过高可能会导致不稳定。
|
Warning
|
超频可能会缩短Raspberry Pi的使用寿命。 如果超频到一定程度会导致系统不稳定，请尝试更适度的超频。在启动期间按住 Shift 键以暂时禁用超频。 |
Fan
自定义GPIO连接的 Raspberry Pi 4 Case Fan 的行为。不适用于其他风扇型号。
Advanced options
|
Warning
|
对高级选项的更改可能会阻止您的Raspberry Pi按预期工作。除非Raspberry Pi工程师指示，否则避免配置高级选项。 |
Expand filesystem
扩展您的操作系统分区以填满整个存储设备，为您提供更多用于文件的空间。重新启动您的Raspberry Pi以完成此操作。通常，Raspberry Pi操作系统在首次启动时运行此操作。如果您将操作系统克隆到比原始存储设备容量更大的单独存储设备，此选项可能很有用。
|
Warning
|
没有确认步骤。选择该选项立即开始分区扩展。 |
Boot order
在Raspberry Pi 4及更高版本上，指定在未检测到SD卡或SSD时是从USB或网络启动。有关详细信息，请参阅 bootloader配置。
non-interactive raspi-config
raspi-config 工具还支持非交互式选项和标志，它们完全在命令行上更改选项，而无需视觉组件。Raspberry Pi型号之间的可用选项可能不同。
$ sudo raspi-config nonint <command> <arguments> [optional-argument]|
Note
|
0 和 1 的含义因选项而异。在将值传递给选项之前，请始终检查留档。
|
System options
Wireless LAN
配置Wi-Fi SSID和密码。
$ sudo raspi-config nonint do_wifi_ssid_passphrase <ssid> <passphrase> [hidden] [plain]如果需要，传递无线网络名称（SSID）和密码。以下标志是可选的：
<hidden> 选项表示SSID的可见性。如果网络广播打开的SSID，则通过 0 或省略该选项。如果您的SSID被隐藏，则通过 1。默认为 0。
<plain>`选项表示是否用额外的引号来封装给定的口令。大多数用户可以忽略该选项：作为一个实现细节，`raspi-config 可能需要在将口令传递给系统其他部分之前添加引号，<plain> 值为`0` 表示已经存在引号。如果值为 1，则表示不存在引号，实施时应根据需要添加引号。默认值为 1。要传递此选项，必须指定 <hidden> 的值。
例如，运行以下命令连接到：
-
名为
myssid的非隐藏网络，密码为mypassphrase:$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid mypassphrase -
名为
myssid的隐藏网络，密码为mypassphrase:$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid mypassphrase 1 -
名为
myssid的非隐藏网络，密码为my passphrase：$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid 'my passphrase' -
名为
myssid的非隐藏网络，并使用口令mypassphrase，在口令中已额外添加了引号：
$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid '"mypassphrase"' 0 0
Audio
指定音频输出目的地。
$ sudo raspi-config nonint do_audio <N>在树莓派4B，您可以使用以下选项：
-
0: bcm2835 headphone jack -
1: vc4-hdmi-0 -
2: vc4-hdmi-1
有关可能的 <N> 值的完整列表，请参阅此选项的交互式 raspi-config 版本中使用的数字。
Password
更改您的密码。
有关详细信息，请参阅 Change a user’s password。
$ sudo raspi-config nonint do_change_pass|
Note
|
此功能使用全屏交互界面，即使从CLI选项运行也是如此。 |
Boot/Auto login
在启动时选择以下行为：
-
是否启动到控制台或桌面
-
开机时树莓派是否自动登录当前用户账户
$ sudo raspi-config nonint do_boot_behaviour <B1/B2/B3/B4>-
B1: 启动到控制台，需要登录 -
B2: 启动到控制台，自动登录 -
B3: 启动到桌面，需要登录 -
B4: 启动到桌面，自动登录
Network at boot
在让引导继续之前等待网络连接。
$ sudo raspi-config nonint do_boot_wait <0/1>-
0: 启动时不等待网络连接 -
1: 等待网络连接后启动
Display options
Underscan
|
Note
|
运行Wayland时不可用。 |
如果屏幕上显示的初始文本从边缘消失，请启用过扫描以调整边框。在某些显示器上，尤其是显示器上，禁用过扫描将使图片充满整个屏幕并删除黑色边框。
$ sudo raspi-config nonint do_overscan_kms <device> <enabled>设备：
-
1: HDMI-1 -
2: HDMI-2
启用：
-
0: enable overscan -
1: disable overscan
VNC resolution
在 headless 设置中定义用于VNC的视频分辨率。
$ sudo raspi-config nonint do_vnc_resolution <width>x<height>Interface options
SSH
启用或禁用远程终端访问您的树莓派使用SSH。
SSH允许您从另一台计算机远程访问Raspberry Pi的命令行。有关SSH的更多信息，请参阅 SSH documentation。
$ sudo raspi-config nonint do_ssh <0/1>-
0: 启用 SSH -
1: 禁用 SSH ==== Raspberry Pi Connect
启用或禁用 Raspberry Pi Connect，无需手动网络配置即可远程访问您的Raspberry Pi。
$ sudo raspi-config nonint do_rpi_connect <0/1>-
0: 启用 Raspberry Pi Connect -
1: 禁用 Raspberry Pi Connect
VNC
启用或禁用虚拟网络计算（VNC）服务器。有关VNC的更多信息，请参阅 VNC documentation。
$ sudo raspi-config nonint do_vnc <0/1>-
0: 启用 VNC -
1: 禁用 VNC
Serial console
在串行连接上启用或禁用shell和内核消息。
$ sudo raspi-config nonint do_serial_cons <0/1>-
0：启用串行端口控制台 -
1：禁用串行端口控制台
Performance options
Overclock
如果您的Raspberry Pi型号允许，请对CPU进行超频。即使在同一型号中，各个Raspberry Pi设备之间的超频潜力也会有所不同。超频过高可能会导致不稳定。
|
Warning
|
超频可能会缩短Raspberry Pi的使用寿命。 如果超频到一定程度会导致系统不稳定，请尝试更适度的超频。启动时按住*Shift*键可暂时禁用超频。 |
$ sudo raspi-config nonint do_overclock <setting>此命令接受以下 <setting> 值：
-
None：无超频（默认） -
Modest：超频至最大值的 50% -
Medium：超频至最大值的 75% -
High：超频至最大值的 100% -
Turbo：超频至最大值的 125%
Overlay file system
启用或禁用只读文件系统。
$ sudo raspi-config nonint do_overlayfs <0/1>-
0：启用只读文件系统 -
1：禁用只读文件系统
Fan
自定义连接GPIO的 Raspberry Pi 4 Case Fan 的行为。此设置不适用于其他风扇型号。
$ sudo raspi-config nonint do_fan <0/1> [gpio] [onTemp]-
0：启用风扇 -
1：禁用风扇
gpio 默认为 14。
onTemp 默认为 80摄氏度。
Localisation options
Locale
选择一个区域设置，例如 en_GB.UTF-8 UTF-8。
$ sudo raspi-config nonint do_change_locale <locale>有关可能的 <locale> 值的完整列表，请参阅此选项的交互式 raspi-config 版本中使用的缩写。
Time zone
以 Region/City 格式设置您的当地时区，例如“欧洲/伦敦”。
$ sudo raspi-config nonint do_change_timezone <timezone>有关可能的 <timezone> 值的完整列表，请参阅此选项的交互式 raspi-config 版本中使用的缩写。
Advanced options
|
Warning
|
对高级选项的更改可能会阻止您的Raspberry Pi按预期工作。除非Raspberry Pi工程师指示，否则避免配置高级选项。 |
Expand filesystem
扩展您的操作系统分区以填满整个存储设备，为您提供更多用于文件的空间。重新启动Raspberry Pi以完成此操作。通常，Raspberry Pi操作系统在首次启动时运行此操作。如果您将操作系统克隆到比原始存储设备容量更大的单独存储设备，此选项可能很有用。
|
Warning
|
没有确认步骤。选择该选项立即开始分区扩展。 |
$ sudo raspi-config nonint do_expand_rootfsNetwork interface names
启用或禁用可预测的网络接口名称。
$ sudo raspi-config nonint do_net_names <0/1>-
0：启用可预测的网络接口名称 -
1：禁用可预测的网络接口名称
Boot order
在Raspberry Pi 4及更高版本上，指定在没有SD卡的情况下是从USB还是网络引导。有关详细信息，请参阅 bootloader configuration 部分。
$ sudo raspi-config nonint do_boot_order <B1/B2/B3>根据您的设备，您可以从以下选项中进行选择：
-
B1：SD 卡启动 - 如果可用，则从 SD 卡启动，否则从 NVMe 启动，否则从 USB 启动 -
B2：NVMe/USB 启动 - 如果可用，则从 NVMe 启动，否则从 USB 启动，否则从 SD 卡启动 -
B3：网络启动 - 如果已插入，则从 SD 卡启动，否则从网络启动
Bootloader version
在Raspberry Pi 4及更高版本上，切换到最新的引导ROM软件。或者，如果最新版本导致问题，您可以恢复出厂默认值。
$ sudo raspi-config nonint do_boot_rom <E1/E2>-
E1：使用最新的启动 ROM -
E2：使用出厂默认设置
Wayland
在X11和Wayland后端之间切换，并选择一个窗口管理器。由于Raspberry Pi OS_Bookworm_，所有Raspberry Pi型号默认使用labwc窗口管理器运行Wayland。
要在树莓派4运行早于_Bookworm_的树莓派操作系统版本之前在树莓派模型上使用Wayland，请将 wayland=on 添加到 /boot/firmware/cmdline.txt。
$ sudo raspi-config nonint do_wayland <W1/W2>-
W1：使用 X11 后端 -
W2：使用 Wayland 后端 -
W3: 使用带有 Wayland 后端的 labwc 窗口管理器
|
Note
|
要在 Raspberry Pi 4 之前的 Raspberry Pi 型号上使用 Wayland，您还必须将 wayland=on 添加到 /boot/firmware/cmdline.txt 。
|
显示
在 GitHub 上修改
要配置 Raspberry Pi 使用非默认显示模式，请手动设置分辨率或旋转。
支持 HDMI 显示器
对于大多数 HDMI 显示器，Raspberry Pi OS 使用显示器支持的最高分辨率和刷新率。
Raspberry Pi Zero、Zero W 和 Zero 2 W 有一个迷你 HDMI 端口，因此您需要迷你 HDMI 转全尺寸 HDMI 的导线或适配器。
从 Raspberry Pi 4B 开始的旗舰机型和键盘机型有两个微型 HDMI 端口，因此您需要为每台要连接的显示器准备一条微型 HDMI 转全尺寸 HDMI 的导线或适配器。在打开 Raspberry Pi 之前连接电缆。
自 Raspberry Pi 4B 开始的旗舰机型、自 CM4 开始的计算模块（CM4S 除外）以及键盘机型最多可驱动两台显示器。
4 系列设备以 60Hz 的刷新率支持高达 1080p 的分辨率，或以 30Hz 的刷新率支持两台 4K 显示器。如果将显示器连接到 HDMI0 端口，并在 /boot/firmware/config.txt 中设置 hdmi_enable_4kp60=1 标志，还能以 60Hz 的刷新率驱动一台 4K 显示器。
5 系列设备无需额外配置，即可以 60hz 的刷新率支持多达两台 4K 分辨率的显示器。
设置分辨率和旋转
在 Raspberry Pi 桌面上，打开 Preferences 菜单，选择 Screen Configuration 实用程序。你会看到连接到 Raspberry Pi 的显示器的图形显示。右键单击要修改的显示屏，然后选择一个选项。单击 Apply 并关闭 Screen Configuration 以保存更改。
或者, 使用以下命令打开 Screen Configuration 组件:
$ raindrop|
Tip
|
如果你的系统不包含 `raindrop`可以使用以下命令安装： 旧版本的 Raspberry Pi OS 使用名为 |
手动设置分辨率和旋转
设置自定义分辨率
要设置自定义分辨率，请使用我们的屏幕配置工具 raindrop。如果您的Raspberry Pi OS安装尚未包含 raindrop（例如，如果您仍在使用以前的屏幕配置工具 arandr），您可以从 apt 或推荐软件GUI下载 raindrop。
设置自定义旋转
要设置自定义分辨率，请使用我们的屏幕配置工具 raindrop。如果您的Raspberry Pi OS安装尚未包含 raindrop（例如，如果您仍在使用以前的屏幕配置工具 arandr），您可以从 apt 或推荐软件GUI下载 raindrop。
如果运行 Wayland 桌面合成器，可以使用 wlr-randr 设置自定义的显示旋转。以下命令可将显示屏旋转 0°、90°、180° 和 270°：
$ wlr-randr --output HDMI-A-1 --transform normal
$ wlr-randr --output HDMI-A-1 --transform 90
$ wlr-randr --output HDMI-A-1 --transform 180
$ wlr-randr --output HDMI-A-1 --transform 270--output 选项指定要旋转的设备。
|
Note
|
要通过 SSH 运行该命令，请添加以下前缀: WAYLAND_DISPLAY=wayland-1，例如 WAYLAND_DISPLAY=wayland-1 wlr-randr --output HDMI-A-1 --transform 90.
|
您还可以使用以下 -transform 选项之一，在旋转显示屏的同时镜像显示屏： flipped, flipped-90, flipped-180, flipped-270
控制台分辨率和旋转
要更改 Raspberry Pi 在控制台模式下的分辨率和旋转，请使用 KMS 设置。更多信息，请参阅 configuring the kernel command line. NOTE: 当使用多台显示器的控制台模式时，所有连接的显示器共享相同的旋转设置。
音频
在 GitHub 上修改
Raspberry Pi OS 有多种音频输出模式： 默认情况下，Raspberry Pi OS 将音频输出到 HDMI 1。
默认情况下，Raspberry Pi OS 将音频输出到 HDMI 1。如果没有 HDMI 输出，Raspberry Pi OS 将音频输出到耳机插孔或连接的 USB 音频设备。
更改音频输出
本节介绍在 Raspberry Pi OS 中配置音频输出的不同方法。
通过桌面音量控制
右键单击系统托盘上的音量图标，打开 音频输出选择器。该界面可让您选择音频输出设备。单击音频输出设备可将音频输出切换到该设备。
专业音频设备配置文件
在音频输出选择器中查看音频设备时，您可能会看到名为 Pro Audio 的设备配置文件。该预案在每个音频设备上都会显示最大数量的通道，让您可以更好地控制信号的路由。除非您需要对音频输出进行微调控制，否则请使用其他设备配置文件。
有关专业音频配置文件的更多信息，请访问 PipeWire常见问题。
通过 raspi-config
要使用 raspi-config 更改音频输出，请运行以下命令：
$ sudo raspi-config您将看到一个配置屏幕。完成以下步骤更改音频输出：
-
选择
System options并按下Enter. -
选择
Audio选项并按下Enter. -
选择所需模式，按
Enter键选择该模式。 -
按向右箭头键退出选项列表。选择
Finish退出配置工具。
配置网络
在 GitHub 上修改
Raspberry Pi OS提供了用于设置无线连接的图形用户交互界面（GUI），Raspberry Pi OS Lite和headless机器的用户可以通过 nmcli 从命令行设置无线网络。
|
Note
|
从 Raspberry Pi OS Bookworm 开始，网络管理器是默认的网络配置工具。早期版本的 Raspberry Pi OS 使用 dhcpd 和其他工具进行网络配置。
|
连接到无线网络
使用桌面
通过菜单栏右端的网络图标访问网络管理器。如果您使用的是具有内置无线连接的Raspberry Pi，或者如果插入了无线加密狗，请单击此图标以显示可用无线网络列表。如果您看到消息’No APs found - scanning…'，请等待几秒钟，网络管理器应该会找到您的网络。
|
Note
|
具有双频无线功能的设备会自动禁用联网功能，直到您分配了一个无线局域网国家。自 Raspberry Pi 3B+ 开始的旗舰机型、自 CM4 开始的计算模块和键盘机型支持双频无线。要设置无线局域网国家，请从首选项菜单打开 Raspberry Pi 配置应用程序，选择 Localisation，然后从菜单中选择您所在的国家。 |
右侧的图标显示网络是否安全，并给出信号强度的指示。单击您要连接的网络。如果网络是安全的，一个对话框将提示您输入网络键：
输入键并单击 OK，然后等待几秒钟。网络图标将短暂闪烁以显示正在建立连接。连接后，图标将停止闪烁并显示信号强度。
使用命令行
本指南将帮助您在不使用图形工具的情况下从终端在Raspberry Pi上配置无线连接。不需要额外的软件。
|
Note
|
本指南应适用于WEP、WPA、WPA2或WPA3网络，但可能不适用于企业网络。 |
启用无线网络
重新安装后，您必须指定使用设备的国家/地区。这允许您的设备为5GHz网络选择正确的频段。指定无线LAN国家/地区后，您可以使用Raspberry Pi的内置无线网络模块。
为此，请使用命令行 raspi-config 工具设置您的无线LAN国家/地区。运行以下命令：
$ sudo raspi-config使用箭头键选择 Localisation options 菜单项。选择 WLAN country 选项。
使用箭头键从下拉列表中选择您的国家/地区。按 Enter 选择您的国家/地区。
您现在应该可以访问无线网络。运行以下命令以检查您的Wi-Fi是否已启用：
$ nmcli radio wifi如果此命令返回文本 "enabled"，则您已准备好配置连接。如果此命令返回 "disabled"，请尝试使用以下命令启用Wi-Fi：
$ nmcli radio wifi on查找网络
要扫描无线网络，请运行以下命令：
$ nmcli dev wifi list您应该会看到类似于以下内容的输出：
IN-USE BSSID SSID MODE CHAN RATE SIGNAL BARS SECURITY
90:72:40:1B:42:05 myNetwork Infra 132 405 Mbit/s 89 **** WPA2
90:72:42:1B:78:04 myNetwork5G Infra 11 195 Mbit/s 79 *** WPA2
9C:AB:F8:88:EB:0D Pi Towers Infra 1 260 Mbit/s 75 *** WPA2 802.1X
B4:2A:0E:64:BD:BE Example Infra 6 195 Mbit/s 37 ** WPA1 WPA2
在"SSID"列中查找您要连接的网络名称。使用SSID和密码连接到网络。
连接网络
运行以下命令配置网络连接，将"<example_ssid>"占位符替换为要配置的网络名称：
$ sudo nmcli --ask dev wifi connect <example_ssid>根据提示输入网络密码。
输入密码后，Raspberry Pi 应该会自动连接网络。
如果出现 "Secrets were required, but not provided"（需要密码，但未提供）的错误输出，说明输入的密码不正确。再次运行上述命令，小心输入密码。
要检查是否已连接到网络，请运行以下命令：
$ nmcli dev wifi list您应该会看到类似于以下内容的输出：
IN-USE BSSID SSID MODE CHAN RATE SIGNAL BARS SECURITY
* 90:72:40:1B:42:05 myNetwork Infra 132 405 Mbit/s 89 **** WPA2
90:72:42:1B:78:04 myNetwork5G Infra 11 195 Mbit/s 79 *** WPA2
9C:AB:F8:88:EB:0D Pi Towers Infra 1 260 Mbit/s 75 *** WPA2 802.1X
B4:2A:0E:64:BD:BE Example Infra 6 195 Mbit/s 37 ** WPA1 WPA2
检查"IN-USE"列中的星号 ( * ) ；它应该与连接上的网络SSID出现在同一行中。
|
Note
|
您可以在 /etc/NetworkManager/system-connections/ 目录中手动编辑您的连接配置。
|
连接到不安全的网络
如果连接的网络不使用密码，请运行以下命令：
$ sudo nmcli dev wifi connect <example_ssid>|
Warning
|
不安全的无线网络会将您的个人信息置于危险之中。尽可能使用安全的无线网络或 VPN。 |
连接到隐藏网络
如果使用的是隐藏网络，请在运行 nmcli 时将 "hidden"（隐藏）选项指定为 "yes"（是）：
$ sudo nmcli --ask dev wifi connect <example_ssid> hidden yes设置网络优先级
如果您的设备同时检测到多个已知网络，它可以连接任何检测到的已知网络。使用优先级选项强制您的Raspberry Pi选择某些网络。您的设备将连接到具有最高优先级的范围内的网络。运行以下命令查看已知网络的优先级：
$ nmcli --fields autoconnect-priority,name connection您应该会看到类似于以下内容的输出：
AUTOCONNECT-PRIORITY NAME 0 myNetwork 0 lo 0 Pi Towers 0 Example -999 Wired connection 1
使用 nmcli connection modify 命令设置网络的优先级。
以下示例命令将名为"Pi Towers"的网络的优先级设置为 10 ：
$ nmcli connection modify "Pi Towers" connection.autoconnect-priority 10您的设备将始终尝试连接到具有最高非负优先级值的范围内网络。您也可以为网络分配负优先级；只有当范围内没有其他已知网络时，您的设备才会尝试连接到负优先级网络。例如，考虑三个网络：
AUTOCONNECT-PRIORITY NAME -1 snake 0 rabbit 1 cat 1000 dog
-
如果所有这些网络都在范围内，您的设备将首先尝试连接到 "dog" 网络。
-
如果与 "dog" 网络的连接失败，您的设备将尝试连接到 "cat" 网络。
-
如果与 "cat" 网络的连接失败，您的设备将尝试连接到 "rabbit" 网络。
-
如果与 "rabbit" 网络的连接失败，并且您的设备没有检测到其他已知网络，您的设备将尝试连接到 "snake" 网络。
配置自动息屏
在 GitHub 上修改
您可以将 Raspberry Pi 配置为在一段时间不活动后自动息屏。默认情况下，启用自动息屏后，Raspberry Pi OS 会在十分钟不活动后自动息屏。
桌面
您可以使用 Raspberry Pi 配置菜单中的 Screen Blanking 选项来控制自动息屏。
控制台
Raspberry Pi Configuration 使用的 dpms_timeout 自动息屏配置仅影响桌面会话。在 控制台模式 下，当您的 Raspberry Pi 连接到显示器和键盘且只有一个终端用于输入时，请在内核命令行中使用 consoleblank 设置。
Users
在 GitHub 上修改
更改用户密码
您可以通过 raspi-config 应用程序或命令行更改当前用户账户的密码：
$ sudo raspi-config选择option 2，然后按照说明更改密码。
或者使用 passwd 应用程序：
$ passwd添加用户
要添加新用户，请输入以下命令，用新用户的用户名替换 <username> 占位符：
$ sudo adduser <username>出现提示时，输入新用户的密码。
新用户的主目录位于 /home/<username>/。
要授予新用户必要的权限（如 sudo），请运行以下命令将用户添加到相关的用户组，并用新用户的用户名替换占位符 <username>：
$ sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,netdev,gpio,i2c,spi <username>要检查权限是否已成功授予，请运行以下命令，用新用户的用户名替换 <username> 占位符：
$ sudo su - <username>如果上述命令运行成功，则说明已成功为用户配置了权限。
外部存储
在 GitHub 上修改
您可以将外部硬盘、SSD或U盘连接到Raspberry Pi上的任何USB端口，然后挂载文件系统以访问存储在其上的数据。
默认情况下，您的Raspberry Pi会在 /media/pi/<HARD-DRIVE-LABEL> 位置自动挂载一些流行的文件系统，例如FAT、NTFS和HFS+。
|
Note
|
Raspberry Pi OS Lite 未使能自动挂载。 |
要将存储设备始终挂载到您选择的特定位置，您必须手动挂载它。
安装存储设备
您可以将存储设备挂载到特定的文件夹位置。通常在 /mnt 文件夹中执行此操作，例如 /mnt/mydisk 。请注意，该文件夹必须为空。
将存储设备插入Raspberry Pi上的USB端口，并使用以下命令列出Raspberry Pi上的所有磁盘分区：
$ sudo lsblk -o UUID,NAME,FSTYPE,SIZE,MOUNTPOINT,LABEL,MODELRaspberry Pi使用挂载点 / 和 /boot/firmware/ 。您的存储设备将与任何其他连接的存储一起显示在此列表中。
使用SIZE、LABEL和MODEL列来标识指向您的存储设备的磁盘分区的名称。例如， sda1 。
FSTYPE列包含文件系统类型。如果您的存储设备使用exFAT文件系统，请安装exFAT驱动程序：
$ sudo apt update
$ sudo apt install exfat-fuse如果您的存储设备使用NTFS文件系统，您将对其具有只读访问权限。如果要写入设备，可以安装ntfs-3g驱动程序：
$ sudo apt update
$ sudo apt install ntfs-3g运行以下命令获取磁盘分区的位置：
$ sudo blkid例如， /dev/sda1 。
创建一个目标文件夹作为存储设备的挂载点。
在这种情况下使用的挂载点名称是 mydisk 。您可以指定您选择的名称：
$ sudo mkdir /mnt/mydisk
将存储设备挂载到刚刚创建的挂载点：
$ sudo mount /dev/sda1 /mnt/mydisk验证存储设备是否已成功挂载：
$ ls /mnt/mydisk设置自动挂载
您可以修改 fstab 文件以定义Raspberry Pi启动时自动挂载存储设备的位置。在 fstab 文件中，磁盘分区由通用唯一标识符（UUID）标识。
获取磁盘分区的UUID：
$ sudo blkid从列表中找到磁盘分区并记下UUID。（例如， 5C24-1453 。）使用命令行编辑器（如nano）打开 fstab 文件：
$ sudo nano /etc/fstab在 fstab 文件中添加以下行：
UUID=5C24-1453 /mnt/mydisk fstype defaults,auto,users,rw,nofail 0 0将 fstype 替换为您在执行上述步骤时找到的文件系统类型，例如： ntfs 。
如果文件系统类型是FAT或NTFS，请在 nofail 之后添加， umask=000` -这将允许所有用户对存储设备上的每个文件进行完全读/写访问。
现在您已经在 fstab 中设置了一个存储设备，您可以在连接或不连接存储设备的情况下启动Raspberry Pi。但是在拔下设备之前，您必须关闭Raspberry Pi，或者手动卸载存储设备。
|
Note
|
如果您在Raspberry Pi启动时没有连接存储设备，则需要额外的90秒才能启动。您可以通过在 nofail 之后立即添加 x-system.device-timeout=30 来缩短时间。这会将超时更改为30秒，这表示系统在放弃尝试挂载磁盘之前只会等待30秒。
|
有关每个Linux命令的更多信息，请参阅使用 man 命令的特定手册页。例如， man fstab 。
内核命令行 (cmdline.txt)
在 GitHub 上修改
Linux 内核在启动过程中接受一系列命令行参数。在 Raspberry Pi 上，该命令行定义在启动分区中一个名为 cmdline.txt 的文件中。您可以使用任何文本编辑器编辑该文本文件。
$ sudo nano /boot/firmware/cmdline.txt|
Important
|
将 cmdline.txt 中的所有参数放在同一行。不要使用换行符。
|
要查看启动时传递给内核的命令行，请运行以下命令：
$ cat /proc/cmdline由于 Raspberry Pi 固件会在启动内核前更改命令行，因此该命令的输出将与 cmdline.txt 中的内容不完全一致。
命令行选项
内核命令行参数有很多，其中一些是由内核本身定义的。其他由内核可能正在使用的代码定义，例如 Plymouth splash。
标准条目
console-
定义串行控制台。通常有两个条目：
-
console=serial0,115200 -
console=tty1
-
root-
定义根文件系统的位置，例如
root=/dev/mmcblk0p2表示多媒体卡块 0 分区 2。 rootfstype-
定义 rootfs 使用的文件系统类型，例如
rootfstype=ext4。 quiet-
将内核日志的默认级别设置为
KERN_WARNING，这样在启动过程中，除了非常严重的日志信息外，所有日志信息都会被抑制。
设置KMS显示模式
设置 KMS 显示模式
早期版本的 Raspberry Pi OS 不再支持传统固件和 FKMS 显示模式。取而代之的是，最近的操作系统版本使用 KMS（内核模式设置）。
如果 cmdline.txt 中没有 video' 条目，Raspberry Pi OS 将使用 HDMI 连接的显示器的 EDID，根据 Linux 内核中的信息自动选择显示器支持的最佳分辨率。在 Raspberry Pi OS Lite 或控制台模式下，您必须自定义 `video 条目以控制分辨率和旋转。
video=HDMI-A-1:1920x1080M@60此外，还可以按照标准 Linux 帧缓冲器文档中的说明添加旋转和反射参数。下面的示例定义了一个名为 HDMI-A-1 的显示器，分辨率为 1080p，刷新率为 60Hz，可旋转 90 度，沿X 轴反转：
video=HDMI-A-1:1920x1080M@60,rotate=90,reflect_x在指定旋转和反射参数时，必须明确指定分辨率。
显示类型的可能选项 - video= 条目的第一部分 - 包括：
| Video Option | Display |
|---|---|
|
HDMI 1 (HDMI 0 on silkscreen of Raspberry Pi 4B, HDMI on single HDMI boards) |
|
HDMI 2 (HDMI 1 on silkscreen of Raspberry Pi 4B) |
|
DSI or DPI |
|
Composite |
其他条目
本节包含一些可以在内核命令行中使用的其他条目。此列表并不详尽。
splash-
通过Plymouth模块告诉启动使用闪屏。
plymouth.ignore-serial-consoles-
如果启用了Plymouth模块，通常会阻止启动信息出现在任何可能存在的串行控制台上。此标记会告诉Plymouth忽略所有串行控制台，使启动信息再次可见，就像Plymouth未运行时一样。
dwc_otg.lpm_enable=0-
关闭 "dwc_otg "驱动程序中的 "链接电源管理（LPM）"，该驱动程序用于驱动 Raspberry Pi 电脑处理器中内置的 USB 控制器。在 Raspberry Pi 4 上，该控制器默认为禁用，并且只连接到 USB C 型电源输入连接器。Raspberry Pi 4 上的 USB-A 端口由单独的 USB 控制器驱动，不受此设置影响。
dwc_otg.speed-
设置 Raspberry Pi 电脑处理器内置 USB 控制器的速度。dwc_otg.speed=1` 将设置为全速（USB 1.0），比高速（USB 2.0）慢。除非在排除 USB 设备故障时，否则不应设置该选项。
smsc95xx.turbo_mode-
启用/禁用有线网络驱动程序的涡轮模式。
smsc95xx.turbo_mode=N关闭涡轮模式。 usbhid.mousepoll-
指定鼠标轮询间隔。如果无线鼠标速度慢或不稳定，使用
usbhid.mousepoll=0将其设置为 0 可能会有帮助。 drm.edid_firmware=HDMI-A-1:edid/your_edid.bin-
用 `/usr/lib/firmware/edid/your_edid.bin`中的内容覆盖显示器的内置 EDID。
保护您的树莓派
在 GitHub 上修改
在这里，我们描述了一些提高Raspberry Pi安全性的常用方法。
更改用户密码
以 sudo 为前缀的命令以超级用户身份运行。默认情况下，超级用户不需要密码。不过，您可以要求所有以 sudo 运行的命令都输入密码，从而提高 Raspberry Pi 的安全性。
要强制 sudo 需要密码，请为您的用户帐户编辑 nopasswd sudoers文件，将文件名中的 <username> 占位符替换为您的用户名：
$ sudo visudo /etc/sudoers.d/010_<username>-nopasswd将 <username> 条目更改为以下内容，将 <username> 替换为您的用户名：
<username> ALL=(ALL) PASSWD: ALL保存文件。您的新首选项应立即生效。
更新树莓派操作系统
只有最新的操作系统发行版才包含所有最新的安全修复。请始终将您的设备 updated 保持在 Raspberry Pi OS 的最新版本。
自动更新 SSH 服务器
如果您使用SSH连接到Raspberry Pi，则值得添加专门更新SSH服务器的 cron 作业。以下命令可能作为每日 cron 作业运行，可确保您立即获得最新的SSH安全修复，独立于正常的更新过程。
$ apt install openssh-server提高SSH安全性
SSH 是远程访问 Raspberry Pi 的常用方法。默认情况下，SSH 需要用户名和密码。要使 SSH 更加安全，请使用 基于密钥的身份验证。
安装防火墙
有许多防火墙解决方案可供Linux使用。大多数使用底层 iptables 项目来提供数据包过滤。该项目位于Linux网络过滤系统之上。默认情况下， iptables 安装在树莓派操作系统上，但没有设置。设置它可能是一项复杂的任务，一个提供比 iptables 更简单界面的项目是 防火墙（UFW）。这是Ubuntu中的默认防火墙工具，可以安装在您的树莓派上：
$ sudo apt install ufwufw 是一个命令行工具，不过也有一些图形用户界面可供使用。请注意，ufw 需要以超级用户权限运行，因此所有命令前都要加上 sudo。也可以使用选项 --dry-run 来运行任何 ufw 命令，它可以显示命令的结果，而不做任何实际修改。
要启用防火墙，这也将确保它在启动时启动，请使用：
$ sudo ufw enable要禁用防火墙并在启动时禁用启动，请使用：
$ sudo ufw disable允许特定端口具有访问权限（我们在示例中使用了端口22）：
$ sudo ufw allow 22拒绝访问端口也很简单（同样，我们以端口22为例）：
$ sudo ufw deny 22您还可以指定在端口上允许或拒绝哪个服务。在此示例中，我们在端口22上拒绝tcp：
$ sudo ufw deny 22/tcp即使您不知道它使用哪个端口，您也可以指定该服务。此示例允许ssh服务通过防火墙访问：
$ sudo ufw allow sshstatus命令列出了防火墙的所有当前设置：
$ sudo ufw status这些规则可能相当复杂，允许阻止特定的IP地址，指定允许哪个方向的流量，或限制尝试连接的次数（例如帮助击败DDoS攻击）。您还可以指定要应用的设备规则（例如eth0、wlan0）。请参阅 ufw 手册页（ man ufw ）以获取以下命令以外的完整详细信息。
使用TCP限制ssh端口上的登录尝试。如果IP地址在过去30秒内尝试连接6次或更多次，这将拒绝连接：
$ sudo ufw limit ssh/tcp拒绝从192.168.2.1地址访问端口30
$ sudo ufw deny from 192.168.2.1 port 30
安装 fail2ban
当把 Raspberry Pi 用作服务器时，你必须设置防火墙以允许服务器流量。http://www.fail2ban.org[Fail2ban] 可以帮助确保服务器安全。Fail2ban 会检查日志文件并检查可疑活动，如多次暴力登录尝试。它能帮你省去手动检查日志文件，然后更新防火墙（通过 iptables ）来阻止入侵尝试的麻烦。
要安装 fail2ban，请运行以下命令：
$ sudo apt install fail2ban安装时，Fail2ban 会创建 /etc/fail2ban/jail.conf。要启用 Fail2ban，请将 jail.conf 复制到 jail.local：
$ sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local该配置文件包含一组默认选项，以及用于检查特定服务异常的选项。要检查用于 ssh 的规则，请在编辑器中打开 jail.local：
$ sudo nano /etc/fail2ban/jail.local如果 [ssh] 部分还不存在，则创建该部分，并在该部分中添加以下行：
[ssh]
enabled = true
port = ssh
filter = sshd
backend = systemd
maxretry = 6这将启用 Fail2ban 检查可疑的 ssh 活动，包括系统日志检查，并允许在阻止活动前重试六次。
同一文件中的 [default] 部分定义了默认禁止操作 iptables-multiport，当达到检测阈值时，该操作将运行 /etc/fail2ban/action.d/iptables-multiport.conf 文件：
# Default banning action (e.g. iptables, iptables-new,
# iptables-multiport, shorewall, etc) It is used to define
# action_* variables. Can be overridden globally or per
# section within jail.local file
banaction = iptables-multiport多端口禁止所有端口的所有访问。action.d 文件夹包含许多可供选择的动作配置文件，您可以用它们来定制服务器对可疑活动的反应。
例如，要在尝试三次失败后永久禁止一个 IP 地址，可将 [ssh] 部分中的 maxretry 值改为 3，并将 bantime 设为负数：
[ssh]
enabled = true
port = ssh
filter = sshd
backend = systemd
maxretry = 3
bantime = -1设置headless树莓派
在 GitHub 上修改
headless Raspberry Pi在没有显示器、键盘或鼠标的情况下运行。要运行headless Raspberry Pi，您需要一种从另一台计算机访问它的方法。要远程访问您的Raspberry Pi，您需要将Raspberry Pi连接到网络，并通过该网络访问Raspberry Pi。
要将Raspberry Pi连接到网络，您可以通过以太网将设备插入有线连接或连接无线网络。
要通过该网络访问您的Raspberry Pi，请使用SSH。通过SSH连接后，如果您喜欢图形桌面环境，可以使用 raspi-config 来使能 VNC。
如果您从头开始设置Raspberry Pi，请在 imaging process 期间设置无线网络和SSH。如果您已经设置了Raspberry Pi，则可以使用 raspi-config 配置SSH。
|
Warning
|
根据您使用的 Raspberry Pi 型号和 SD 卡类型，您的 Raspberry Pi 首次启动和连接到无线网络可能需要长达五分钟的时间。 |
连接到有线网络
要在首次启动时连接到有线网络，请通过以太网插入headless Raspberry Pi，如果您的Raspberry Pi型号没有网口，请使用以太网适配器。您的Raspberry Pi将自动连接到网络。
连接到无线网络
要在 headless Raspberry Pi 中首次启动时配置无线网络访问，请使用 Raspberry Pi Imager 中的高级设置菜单。输入首选无线网络的SSID和密码。您的Raspberry Pi将在首次启动时使用这些凭据连接到网络。某些无线适配器和某些Raspberry Pi板不支持5GHz网络；检查无线模块的文档，以确保与选择的网络兼容。
|
Note
|
以前版本的Raspberry Pi OS使用 wpa_supplicant.conf 文件，该文件可以放置在引导文件夹中以配置无线网络设置。此功能从 Raspberry Pi OS Bookworm 开始不可用。
|
远程访问
如果没有键盘或显示器，您需要一种方法来 远程控制 您的headless Raspberry Pi。首次启动时，唯一可用的选项是SSH。要在新安装的Raspberry Pi OS上启用SSH，请选择以下方法之一：
-
在 Raspberry Pi Imager 的操作系统自定义菜单中启用SSH，然后输入用户名和密码
-
在 SD 卡第一个分区（标为
bootfs）的根目录下创建名为ssh的文件，然后按照下面部分的说明使用userconf.txt手动配置用户
手动配置用户
在 SD 卡第一部分的根目录下（文件系统标记为 bootfs），创建一个名为 userconf.txt 的文件。
此文件应包含一行文本，由 <username>：<password> 组成：您想要的用户名，后跟冒号，后跟您想要使用的密码的 加密 表示。
|
Note
|
<username> 只能包含小写字母、数字和连字符，并且必须以字母开头。它不能超过31个字符。
|
要生成加密密码，请在另一台计算机上使用 OpenSSL。打开终端并输入以下内容：
$ openssl passwd -6出现提示时，输入您的密码并进行验证。然后，此命令将输出提供的密码的加密版本。
在 Raspberry Pi 上托管无线网络
在 GitHub 上修改
Raspberry Pi 可以使用无线模块托管自己的无线网络。如果您通过以太网端口（或第二个无线模块）将 Raspberry Pi 连接到互联网，则连接到无线网络的其他设备可以通过 Raspberry Pi 访问互联网。
考虑使用 10.x.x.x IP 块的有线网络。您可以将 Raspberry Pi 连接到该网络，并在使用另一个 IP 块（例如 192.168.x.x ）的单独网络上为无线客户端提供服务。
在下图中，请注意笔记本电脑存在于与路由器和有线客户端分开的 IP 块中：
使用此网络配置，无线客户端都可以通过 Raspberry Pi 路由器相互通信。但是，无线网络上的客户端无法直接与有线网络上的客户端（Raspberry Pi 除外）交互；无线客户端存在于与为有线客户端提供服务的网络分开的私有网络中。
|
Note
|
Raspberry Pi 5、4、3、Zero W 和 Zero 2 W 可以使用内置无线模块托管无线网络。没有内置模块的 Raspberry Pi 型号可使用单独的无线加密狗支持该功能。 |
启用热点
要在命令行上创建托管无线网络，请运行以下命令，将 <example-network-name> 和 <example-password> 占位符替换为您自己的值：
$ sudo nmcli device wifi hotspot ssid <example-network-name> password <example-password>使用另一个无线客户端（例如笔记本电脑或智能手机）连接到网络。查找 SSID 与 <example-network-name> 匹配的网络。输入您的网络密码，您应该可以成功连接到网络。如果您的 Raspberry Pi 通过以太网连接或第二个无线适配器访问互联网，您应该能够访问互联网。
禁用热点
要禁用热点网络并恢复使用 Pi 作为无线客户端，请运行以下命令：
$ sudo nmcli device disconnect wlan0禁用网络后，运行以下命令重新连接到另一个 Wi-Fi 网络：
$ sudo nmcli device up wlan0|
Tip
|
有关连接无线网络的更多信息，请参阅 配置网络。 |
使用 Raspberry Pi 作为网桥
默认情况下，Raspberry Pi 托管的无线网络与通过以太网连接的父网络分开存在。在这种安排下，连接到父网络的设备无法直接与连接到 Raspberry Pi 托管的无线网络的设备通信。如果您希望连接的无线设备能够与父网络上的设备通信，您可以将 Raspberry Pi 配置为 网桥。建立网络桥接后，连接到 Pi 托管无线网络的每个设备都会在父网络中分配一个 IP 地址。
在下图中，笔记本电脑与路由器和有线客户端存在于同一 IP 网段中：
以下步骤介绍了如何在 Raspberry Pi 上设置网络桥接，以启用无线客户端和父网络之间的通信。
首先，创建一个网络桥接接口：
$ sudo nmcli connection add type bridge con-name 'Bridge' ifname bridge0接下来，将设备与父网络的以太网连接添加到桥接器：
$ sudo nmcli connection add type ethernet slave-type bridge \
con-name 'Ethernet' ifname eth0 master bridge0最后，将您的无线热点连接添加到桥接器。您可以添加现有热点接口或创建新接口：
-
如果您已使用上述说明创建了无线热点连接，请使用以下命令将现有接口添加到网桥：
$ sudo nmcli connection modify 'Hotspot' master bridge0 -
如果您尚未创建无线热点连接，请使用单个命令创建一个新接口并将其添加到网桥，将
<hotspot-ssid><hotspot-password>占位符替换为您选择的热点和密码：$ sudo nmcli connection add con-name 'Hotspot' \ ifname wlan0 type wifi slave-type bridge master bridge0 \ wifi.mode ap wifi.ssid <hotspot-ssid> wifi-sec.key-mgmt wpa-psk \ wifi-sec.proto rsn wifi-sec.pairwise ccmp \ wifi-sec.psk <hotspot-password>
配置好网桥后，就该激活它了。运行以下命令激活网桥：
$ sudo nmcli connection up Bridge并运行以下命令开始托管您的无线网络：
$ sudo nmcli connection up Hotspot您可以使用 nmcli device 命令来验证网桥、以太网接口和无线热点接口是否都处于活动状态。
|
Tip
|
一旦连接到热点，使用 arp-scan 等工具检查父网络上的设备是否可访问。 |
使用代理服务器
在 GitHub 上修改
proxy server 是客户端设备和互联网之间的中介。 要将 Raspberry Pi 配置为代理服务器客户端，请按照本节的说明操作。
您将需要：
-
您的代理服务器的IP地址或主机名和端口
-
您的代理的用户名和密码（如果需要）
配置您的Raspberry Pi
您需要设置三个环境变量（http_proxy、https_proxy 和 no_proxy），以便您的Raspberry Pi知道如何访问代理服务器。
打开一个终端窗口，并使用 nano 打开文件 /etc/environment ：
$ sudo nano /etc/environment将以下内容添加到 /etc/environment 文件以创建 http_proxy 变量：
export http_proxy="http://<proxy_ip_address>:<proxy_port>"将 <proxy_ip_address> 和 <proxy_port> 占位符替换为代理的 IP 地址和端口。
|
Note
|
如果代理需要用户名和密码，请使用以下格式添加： 将 |
为环境变量 https_proxy输入相同的信息：
export https_proxy="http://username:password@proxyipaddress:proxyport"创建no_proxy环境变量，这是一个逗号分隔的地址列表，您的Raspberry Pi不应将代理用于：
export no_proxy="localhost, 127.0.0.1"现在您的 /etc/environment 文件应该如下所示：
export http_proxy="http://username:password@proxyipaddress:proxyport"
export https_proxy="http://username:password@proxyipaddress:proxyport"
export no_proxy="localhost, 127.0.0.1"按 Ctrl + X 保存并退出。
boot 文件夹内容
在 GitHub 上修改
Raspberry Pi OS将引导文件存储在SD卡的第一个分区上，使用FAT文件系统。
启动时，每个Raspberry Pi都会从引导分区加载各种文件，以便在Linux内核启动之前启动各种处理器。
在引导时，Linux将引导分区挂载为 /boot/firmware/ 。
|
Note
|
在 Bookworm 之前，树莓派操作系统将引导分区存储在 /boot/ 。从 Bookworm 开始，引导分区位于 /boot/firmware/ 。
|
bootcode.bin
引导加载程序，由SoC在引导时加载。它执行一些非常基本的设置，然后加载其中一个 start*.elf 文件。
Raspberry Pi 4和5不使用bootcode.bin。它已被 板载EEPROM 中的引导代码代替。
start*.elf
二进制固件块加载到 SoC 中的 VideoCore GPU 上，然后接管启动过程。
start.elf-
基本固件。
start_x.elf-
包含额外的编解码器。
start_db.elf-
用于调试。
start_cd.elf-
固件的精简版，删除了对编解码器和 3D 等硬件模块的支持以及调试日志支持；它还施加了初始帧缓冲区限制。如果在
config.txt中指定了gpu_mem=16，则会自动使用精简版固件。
start4.elf , start4x.elf , start4db.elf 和 start4cd.elf 是特定于Raspberry Pi 4系列（Model 4B, Pi 400, Compute Module 4 和 Compute Module 4S）的同功能固件文件。
有关如何使用这些文件的详细信息，请参阅 config.txt 文档.
Raspberry Pi 5 不使用 elf 文件。固件独立包含在引导加载程序EEPROM中。
cmdline.txt
启动时传入内核的 kernel command line
config.txt
包含用于设置Raspberry Pi的许多配置参数。有关详细信息，请参阅 config.txt 文档.。
|
Important
|
Raspberry Pi 5 要求启动分区中有一个非空的 config.txt 文件。
|
initramfs*
初始ramdisk的内容。这会在挂载真正的根文件系统之前将临时根文件系统加载到内存中。
从 Bookworm 开始，Raspberry Pi OS 默认包含一个 initramfs 文件。要启用初始 ramdisk，请在 config.txt 中使用 auto_initramfs 关键字进行配置。
ssh 或 ssh.txt
如果存在该文件，则在启动时启用 SSH。否则 SSH 默认为禁用。文件内容并不重要。即使是空文件也能启用 SSH。
|
Note
|
内容无关紧要。即使是一个空文件也可以使能SSH。 |
设备树blob文件 ( *.dtb )
设备树blob文件包含Raspberry Pi各种型号的硬件定义。这些文件在引导 基于检测到的Raspberry Pi模型。
内核文件 ( *.img )
与树莓派型号对应的各种 kernel 内核文件：
| 文件名 | 处理器 | 型号 | 说明 |
|---|---|---|---|
|
BCM2835 |
Pi Zero, Pi 1 |
|
|
BCM2836， BCM2837 |
Pi Zero 2 W, Pi 2, Pi 3 |
后续Pi 2使用BCM2837 |
|
BCM2711 |
Pi 4, CM4, CM4S, Pi 400 |
大型物理地址扩展 (LPAE) |
|
BCM2837、BCM2711、BCM2712 |
Pi Zero 2 W, Pi 2 (后续版本), Pi 3, CM3, Pi 3+, CM3+, Pi 4, CM4, CM4S, Pi 400, CM5, Pi 5, Pi 500 |
64位内核。带有BCM2836的Raspberry Pi 2不支持64位内核。 |
|
BCM2712 |
Pi 5, CM5, Pi 500 |
Pi 5优化的 64-bit kernel。 |
|
Note
|
对于运行 32 位内核的系统，lscpu 报告的 CPU 架构为 armv7l；对于运行 64 位内核的系统，aarch64 报告的 CPU 架构为 armv7l。armv7l 中的 l`指的是小端 CPU 架构，而不是 `kernel7l.img 文件名中的 l 所表示的 LPAE。
|
overlays 文件夹
包含设备树overlay。这些用于配置各种硬件设备，例如第三方声卡。通过修改 config.txt 中的配置选择这些overlay。有关详细信息，请参阅 Device Trees, overlays and parameters。
LED闪烁警告
在 GitHub 上修改
如果Raspberry Pi由于某种原因无法启动或必须关闭，在许多情况下，LED会闪烁特定次数以指示发生了什么。LED会闪烁多次长时间闪烁（0或更多），然后产生短时间闪烁，以指示确切的状态。在大多数情况下，该模式会在两秒钟的间隙后重复。
| Long flashes | Short flashes | Status |
|---|---|---|
0 |
3 |
Generic failure to boot |
0 |
4 |
start*.elf not found |
0 |
7 |
Kernel image not found |
0 |
8 |
SDRAM failure |
0 |
9 |
Insufficient SDRAM |
0 |
10 |
In HALT state |
2 |
1 |
Partition not FAT |
2 |
2 |
Failed to read from partition |
2 |
3 |
Extended partition not FAT |
2 |
4 |
File signature/hash mismatch - Pi 4 and Pi 5 |
3 |
1 |
SPI EEPROM error - Pi 4 and Pi 5 |
3 |
2 |
SPI EEPROM is write protected - Pi 4 and Pi 5 |
3 |
3 |
I2C error - Pi 4 and Pi 5 |
3 |
4 |
Secure-boot configuration is not valid |
4 |
3 |
RP1 not found |
4 |
4 |
Unsupported board type |
4 |
5 |
Fatal firmware error |
4 |
6 |
Power failure type A |
4 |
7 |
Power failure type B |
配置 UART
在 GitHub 上修改
Raspberry Pi 上有两种类型的 UART - PL011 和 mini UART。PL011 是一款功能强大、广泛兼容 16550 的 UART，而 mini UART 的功能集则有所减少。
Raspberry Pi 上的所有 UART 都仅为 3.3V - 如果将它们连接到 5V 系统，则会发生损坏。可以使用适配器连接到 5V 系统。或者，可以从各种第三方获得低成本的 USB 转 3.3V 串行适配器。
Raspberry Pi Zero、1、2 和 3
Raspberry Pi Zero、1、2 和 3 各包含两个 UART，如下所示：
| 名称 | 类型 |
|---|---|
UART0 |
PL011 |
UART1 |
mini UART |
Raspberry Pi 4 和 400
Raspberry Pi 4 Model B 和 400 有另外四个 PL011，默认情况下处于禁用状态：
| 名称 | 类型 |
|---|---|
UART0 |
PL011 |
UART1 |
mini UART |
UART2 |
PL011 |
UART3 |
PL011 |
UART4 |
PL011 |
UART5 |
PL011 |
Raspberry Pi 5
Raspberry Pi 5 有另外四个 PL011，默认情况下处于禁用状态：
| 名称 | 类型 |
|---|---|
UART0 |
PL011 |
UART1 |
PL011 |
UART2 |
PL011 |
UART3 |
PL011 |
UART4 |
PL011 |
Raspberry Pi 5 没有Mini-UART。
CM1、CM3、CM3+ 和 CM4
第一代计算模块以及计算模块 3 和计算模块 3+ 有两个 UART，而计算模块 4 有六个 UART，如上所述。
在所有型号的计算模块上，UART 默认处于禁用状态，可以使用设备树覆盖明确启用。您还可以指定要使用的 GPIO 引脚，例如：
dtoverlay=uart1,txd1_pin=32,rxd1_pin=33主 UART
在 Raspberry Pi 上，GPIO 14（发送）和 15（接收）上有一个 UART 被选择为主 UART。默认情况下，这也是 Linux 控制台可能使用的 UART。请注意，GPIO 14 是 GPIO 针座上的第 8 针，而 GPIO 15 是第 10 针。
在 Raspberry Pi 5 上，主 UART 为调试接头。
主 UART 和辅助 UART
下表总结了各种 Raspberry Pi 设备上 UART 的分配：
| 型号 | 主/控制台 | 辅助/蓝牙 |
|---|---|---|
Raspberry Pi Zero |
UART0 |
UART1 |
Raspberry Pi Zero W / Raspberry Pi Zero 2 W |
UART1 |
UART0 |
Raspberry Pi 1 |
UART0 |
UART1 |
Raspberry Pi 2 |
UART0 |
UART1 |
Raspberry Pi 3 |
UART1 |
UART0 |
Compute Module 3 & 3+ |
UART0 |
UART1 |
Raspberry Pi 4 |
UART1 |
UART0 |
Raspberry Pi 5 |
UART10 |
<dedicated UART> |
Raspberry Pi OS 上的 Linux 设备：
| Linux 设备 | 说明 |
|---|---|
|
mini UART |
|
first PL011 (UART0) |
|
primary UART |
|
secondary UART |
|
Raspberry Pi 5 Debug UART |
/dev/serial0 和 /dev/serial1 是指向 /dev/ttyS0 或 /dev/ttyAMA0 的符号链接。
在 Raspberry Pi 5 上， /dev/serial0 是指向 /dev/ttyAMA10 的符号链接。
由于 Bookworm 中的更改，默认情况下不存在 /dev/serial1 。 您可以通过在 config.txt 中设置以下值来重新启用 serial1 ：
dtparam=krnbt=off|
Tip
|
此选项将来可能无法在所有型号上工作。 仅在您的用例没有其他替代方案时才使用此选项。 |
Mini-UART 和 CPU 核心频率
|
Note
|
如果 mini UART 是主 UART 或蓝牙被禁用，则默认情况下会禁用 mini UART。 |
为了使用Mini-UART，您需要将 Raspberry Pi 配置为使用固定的 VPU 核心时钟频率。这是因为Mini-UART 时钟与 VPU 核心时钟相连，因此当核心时钟频率发生变化时，UART 波特率也会发生变化。可以将 enable_uart 和 core_freq 设置添加到 config.txt 以更改Mini-UART 的行为。下表总结了可能的组合：
| Mini UART set to | core clock | Result |
|---|---|---|
primary UART |
variable |
mini UART disabled |
primary UART |
fixed by setting |
mini UART enabled, core clock fixed to 250MHz, or if |
secondary UART |
variable |
mini UART disabled |
secondary UART |
fixed by setting |
mini UART enabled |
The default state of the enable_uart flag depends on which UART is the primary UART:
| Primary UART | Default state of enable_uart flag |
|---|---|
mini UART |
0 |
first PL011 (UART0) |
1 |
禁用Linux串行控制台
默认情况下，主通用异步收发设备被分配到Linux控制台。如果您希望将主通用异步收发设备用于其他目的，您必须重新配置Raspberry Pi OS。这可以通过使用 raspi-config 来完成：
-
启动 raspi-config:
sudo raspi-config -
选择选项 3 - Interface Options
-
选择选项 P6 - Serial Port
-
在提示
Would you like a login shell to be accessible over serial?时，回答 "否" -
在提示
Would you like the serial port hardware to be enabled?时，回答 "是" -
退出
raspi-config并重启 Raspberry Pi 以使更改生效
为Linux启用早期控制台
尽管Linux内核在引导过程中相对较早地启动了UART，但在基础设施的一些关键部分启动之后仍然需要很长时间。如果不访问当时的内核日志消息，则很难诊断这些早期阶段的故障。要启用对其中一个UART的 earlycon ，可根据哪个 UART 是主 UART，在 cmdline.txt 中添加以下选项之一：
对于 Raspberry Pi 5， earlycon 输出只出现在 3 针调试连接器上，配置如下：
earlycon=pl011,0x107d001000,115200n8对于Raspberry Pi 4, Compute Module 4, Compute Module 4S, 和 Pi 400:
earlycon=uart8250,mmio32,0xfe215040
earlycon=pl011,mmio32,0xfe201000对于Raspberry Pi 2, 3, 3+, Zero 2 W, Compute Module 3, 和 Compute Module 3+:
earlycon=uart8250,mmio32,0x3f215040
earlycon=pl011,mmio32,0x3f201000对于Raspberry Pi 1, Zero, Zero W, 和 Compute Module 1:
earlycon=uart8250,mmio32,0x20215040
earlycon=pl011,mmio32,0x20201000波特率默认为115200bps。
|
Note
|
选择错误的早期控制台会阻碍Raspberry Pi启动。 |
UART和设备树
各种通用异步收发设备树覆盖定义可以在 内核GitHub 中找到。两个最有用的overlay disable-bt 和 miniuart-bt。
disable-bt 禁用蓝牙设备并使第一个PL011（UART0）成为主要的通用异步收发设备。您还必须禁用初始化调制解调器的系统服务，使其不连接到通用异步收发设备，使用 sudo systemctl disable hciuart 。
miniuart-bt 将蓝牙功能切换为使用 mini UART，并使第一个PL011（UART0）成为primary UART。请注意，这可能会降低最大可用波特率（请参阅下面的迷你通用步异步收发设备限制）。您还必须使用 force_turbo=1 或 core_freq=250 将VPU核心时钟设置为固定频率。
overlay uart2、 uart3、 uart4 和 uart5 用于在Raspberry Pi 4上启用另外四个UART。文件夹中还有其他通用异步收发设备特定的overlay。有关设备树overlay的详细信息，请参阅 /boot/firmware/overays/README ，或运行 dtoverlay-h overlay-name 以获取描述和使用信息。
您可以在config.txt文件中添加一行以应用 Device Tree overlay。请注意，文件名的 -overlay.dts 部分已被删除。例如：
dtoverlay=disable-btPL011和 mini-UART
PL011 UART和 mini-UART有一些区别。
mini-UART的FIFO较小。加上缺乏流量控制，这使得它更容易在更高的波特率下丢失字符。它的能力通常也不如PL011，主要是因为它的波特率链接到 VPU 时钟速度。
与PL011相比，微型通用异步收发设备的具体缺陷是：
-
无断线检测
-
无成帧错误检测
-
无奇偶校验位
-
无接收超时中断
mini-UART和PL011的BCM2835实现都没有DCD、DSR、DTR或RI信号。
有关mini UART的更多文档，请参见 SoC外围设备文档。
Device Trees, overlays, 和 parameters
在 GitHub 上修改
Raspberry Pi 内核和固件使用设备树（DT）来描述硬件。这些设备树可能包括用于控制板上功能的 DT 参数。DT 覆盖层允许对可选的外部硬件进行描述和配置，它们还支持更多控制参数。
固件加载器（ start.elf 及其变体）负责加载DTB（Device Trees Blob-机器可读的DT文件）。它根据产品型号选择要加载的版本，并进行修改。这种方式避免了对许多只有微小的差异DTB的需求，
读取 config.txt 中用户提供的参数，以及所有 overlay 及其参数，然后使用它们。加载程序检查结果来确认（例如）控制台将使用哪个通用异步收发设备（如果有）。最后它启动内核，并传递一个指向合并后DTB的指针。
Device Trees
Device Trees（Device Tree，DT）是对系统中硬件的描述。它应该包括基本CPU的名称、内存配置和所有外设（内部和外部）。DT不应该用于描述软件，尽管通过给出的硬件模块，它通常会加载对应驱动程序模块。
|
Note
|
这有助于记住DT应该是操作系统中立的，所以任何特定于Linux的东西都不应该存在。 |
Device Trees 将硬件配置表示为节点的层次结构。每个节点可能包含属性和子节点。属性被命名为字节数组，其中可能包含字符串、数字（大端）、任意字节序列以及它们的任何组合。通过类比文件系统，节点是目录，属性是文件。树中节点和属性的位置可以使用路径来描述，斜杠作为分隔符，单个斜杠 ( / ) 表示根。
基本DTS语法
Device Trees通常用称为Device Trees源（DTS）的文本形式编写，并保存在带有 .dts 后缀的文件中。DTS语法类似于C，带有用于分组的大括号和每行末尾的分号。请注意，DTS在关闭大括号后需要分号：就像C语言中的 struct 而不是函数。编译后的二进制格式称为 Flattened Device Tree（FDT）或 Device Tree Blob (DTB)，并存储在 .dtb 文件中。
以下是一个简单的 .dts 格式设备树：
/dts-v1/;
/include/ "common.dtsi";
/ {
node1 {
a-string-property = "A string";
a-string-list-property = "first string", "second string";
a-byte-data-property = [0x01 0x23 0x34 0x56];
cousin: child-node1 {
first-child-property;
second-child-property = <1>;
a-string-property = "Hello, world";
};
child-node2 {
};
};
node2 {
an-empty-property;
a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */
child-node1 {
my-cousin = <&cousin>;
};
};
};
/node2 {
another-property-for-node2;
};这棵树包含：
-
必需的标头：
/dts-v1/ -
包含另一个DTS文件，通常命名为
*.dtsi，类似于C中的.h头文件 -
单个根节点：
/ -
几个子节点：
node1和node2 -
node1的一些子节点：
child-node1和child-node2 -
标签 (
cousin) 和对该标签的引用 (&cousin) -
几个分散的属性
-
一个重复节点（
/node2）
属性是简单的键值对，其值可以为空，也可以包含任意字节。虽然数据类型未在数据结构中编码，但有一些基本datasheet示可以在 Device Trees 源文件中表示。
文本字符串（以NUL结尾）用双引号表示：
string-property = "a string";单元格是由尖括号分隔的32位无符号整数：
cell-property = <0xbeef 123 0xabcd1234>;任意字节数据用方括号分隔，并以十六进制输入：
binary-property = [01 23 45 67 89 ab cd ef];不同表示的数据可以使用逗号连接：
mixed-property = "a string", [01 23 45 67], <0x12345678>;逗号也用于创建字符串列表：
string-list = "red fish", "blue fish";
关于 /include/ 的介绍
通过 /include/ 指令实现简单的文本包含，很像 C 的 #include 指令，但设备树编译器的一个特性导致不同的使用模式。由于节点是以绝对路径命名的，同一节点有可能在 DTS 文件（及其包含文件）中出现两次。出现这种情况时，节点和属性会合并，根据需要交错并覆盖属性（后面的值覆盖前面的值）。
在上面的示例中， /node2 的第二次出现会导致在原始属性中添加一个新属性：
/node2 {
an-empty-property;
a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */
another-property-for-node2;
child-node1 {
my-cousin = <&cousin>;
};
};因此，一个 .dtsi 可以覆盖设备树中的多个位置或为其提供默认值。
标签和引用
树的一部分通常需要引用另一个部分，有四种方法可以做到这一点：
- Path strings
-
与文件系统路径类似，例如
/soc/i2s@7e203000是 BCM2835 和 BCM2836 中 I2S 设备的完整路径。标准 API 不会创建类似 `/soc/i2s@7e203000/status`这样的属性路径：而是首先找到一个节点，然后选择该节点的属性。 - Phandles
-
在节点的
phandle属性中分配给节点的唯一 32 位整数。由于历史原因，你可能还会看到一个多余的、匹配的linux,phandle。phandle 按顺序编号，从 1 开始；0 不是有效的 phandle。当 DT 编译器在整数上下文中遇到对节点的引用时，通常会以标签的形式分配它们。对使用 phandle 的节点的引用会被简单地编码为相应的整数（单元格）值；没有标记表明它们应被解释为 phandle，因为这是由应用程序定义的。 - Labels
-
就像 C 语言中的标签给代码中的一个位置命名一样，DT 标签也给层次结构中的一个节点命名。编译器会引用标签，并在字符串上下文（
&node）中将其转换为路径，在整数上下文（<&node>）中将其转换为phandles；原始标签不会出现在编译输出中。请注意，标签不包含任何结构；它们只是平面全局名称空间中的标记。 - Aliases
-
与标签类似，但它们作为一种索引形式出现在 FDT 输出中。它们存储为
/aliases节点的属性，每个属性将别名映射为路径字符串。虽然别名节点出现在源代码中，但路径字符串通常是作为对标签 (&node)的引用出现，而不是全部写出。将路径字符串解析为节点的 DT API 通常会查看路径的第一个字符，将不以斜线开头的路径视为别名，必须首先使用/aliases表将其转换为路径。
Device Tree 语义
如何构建Device Trees，以及如何最好地使用它来捕获某些硬件的配置，是一个庞大而复杂的主题。有许多可用的资源，其中一些如下所列，但有几点值得强调：
-
compatible属性是硬件描述和驱动程序软件之间的联系。当操作系统遇到具有compatible属性的节点时，它会在其设备驱动程序数据库中查找它以找到最佳匹配项。在Linux，这通常会自动加载驱动程序模块，但前提是它已经被适当标记并且没有被列入黑名单。 -
status属性表示设备是启用还是禁用。如果status为ok、okay或缺失，则表示设备已启用。否则，"status "应为 "disabled"，这样设备就被禁用了。将状态设置为 "disabled "的设备放在.dtsi文件中可能很有用。派生配置可以包含该.dtsi文件，并将所需设备的状态设置为okay。
Device Tree overlays
片上系统（SoC）是一个非常复杂的设备；一个完整的 Device Trees 可能有数百行长。更进一步，把SoC和其他组件放在一块板上只会让事情变得更加复杂。为了保持这种可管理性，对于有相同组件的相关设备，把公共元素放在 .dtsi 文件中是有意义的，这些元素可能包含在多个 .dts 文件中。
当像Raspberry Pi这样的系统还支持可选的插件附件（如HAT）时，问题就会增加。最终，每个可能的配置都需要一个Device Trees来描述它，但是一旦你考虑到所有不同的基本模型和大量可用的附件，组合的数量就会开始迅速增加。
除非您想学习如何为Raspberry Pis编写overlays，否则您可能更愿意跳过 Use Device Trees。
Fragments
DT overlay 包含许多片段，每个片段都针对一个节点及其子节点。虽然这个概念听起来很简单，但一开始语法似乎很奇怪：
//启用i2s接口
/dts-v1/;
/plugin/;
/ {
compatible = "brcm,bcm2835";
fragment@0 {
target = <&i2s>;
__overlay__ {
status = "okay";
test_ref = <&test_label>;
test_label: test_subnode {
dummy;
};
};
};
};compatible 字符串将其标识为BCM2835，这是Raspberry Pi SoC的基本架构；如果 overlay 使用了Raspberry Pi 4的功能，则应该使用 brcm,bcm2711 ，否则就应该使用 brcm,bcm2835 ，它可用于所有Raspberry Pi overlays。然后是第一个（仅在本例中）片段。片段应从0开始按顺序编号。不遵守这一点可能会导致部分或全部片段被遗漏。
每个片段由两部分组成：一个 target 属性，标识要应用overlay的节点；和 __overlay__ 本身，其主体被添加到目标节点。上面的例子可以解释为它是这样写的：
/dts-v1/;
/plugin/;
/ {
compatible = "brcm,bcm2835";
};
&i2s {
status = "okay";
test_ref = <&test_label>;
test_label: test_subnode {
dummy;
};
};使用新的 dtc 版本，你就可以完全按照上面的方法编写示例，并获得相同的输出，但有些自制工具还不能理解这种格式。您可能希望在标准 Raspberry Pi 操作系统内核中包含的任何overlay都应暂时以旧格式编写。
如果之后加载overlay，将该overlay与标准Raspberry Pi基础Device Trees（例如 bcm2708-rpi-b-plus.dtb ）合并的效果是通过将其状态更改为 okay 来启用I2S接口。但是如果您尝试使用以下方式编译此overlay：
$ dtc -I dts -O dtb -o 2nd.dtbo 2nd-overlay.dts…您将收到错误：
Label or path i2s not found
这应该不会太出乎意料，因为没有对基本 .dtb 或 .dts 文件的引用来允许编译器找到 i2s 标签。
再次尝试，这次使用原始示例并添加 -@ 选项以允许未解析的引用（和 -Hepapr 以减少一些混乱）：
$ dtc -@ -Hepapr -I dts -O dtb -o 1st.dtbo 1st-overlay.dts如果 dtc 返回有关第三行的错误信息，说明它没有编译设备树的软件。运行 sudo apt install device-tree-compiler 并再试一次，这次编译应该会成功完成。请注意，内核树中也有一个合适的编译器，即 scripts/dtc/dtc ，在使用 dtbs make target 时编译：
$ make ARCH=arm dtbs转储DTB文件的内容以查看编译器生成了什么：
$ fdtdump 1st.dtbo输出结果应与下面类似：
/dts-v1/;
// magic: 0xd00dfeed
// totalsize: 0x207 (519)
// off_dt_struct: 0x38
// off_dt_strings: 0x1c8
// off_mem_rsvmap: 0x28
// version: 17
// last_comp_version: 16
// boot_cpuid_phys: 0x0
// size_dt_strings: 0x3f
// size_dt_struct: 0x190
/ {
compatible = "brcm,bcm2835";
fragment@0 {
target = <0xffffffff>;
__overlay__ {
status = "okay";
test_ref = <0x00000001>;
test_subnode {
dummy;
phandle = <0x00000001>;
};
};
};
__symbols__ {
test_label = "/fragment@0/__overlay__/test_subnode";
};
__fixups__ {
i2s = "/fragment@0:target:0";
};
__local_fixups__ {
fragment@0 {
__overlay__ {
test_ref = <0x00000000>;
};
};
};
};在对文件结构的详细描述之后是我们的片段。但是仔细看——我们写 &i2s 的地方现在写着 0xffffffff ，这是一个奇怪的事情的线索（旧版本的dtc可能会说 0xdebef ）。编译器还添加了一个 phandle 属性，其中包含一个唯一的（到这个overlay）小整数来指示节点有一个标签，并用相同的小整数替换对标签的所有引用。
在 fragment 之后有三个新节点：
-
__symbols__列出了 overlay 中使用的标签（此处为test_label），以及通往标签节点的路径。这个节点是如何处理未解决符号的关键。 -
__fixups__包含一个属性列表，它将未解决符号的名称映射到片段中需要用目标节点的 phandle 进行修补的单元格的路径列表，一旦找到目标节点。在本例中，路径指向target的0xffffffffff值，但片段可能包含其他未解决的引用，需要额外的修补。 -
__local_fixups__保存了 overlay 中存在的任何标签引用的位置--test_ref属性。之所以需要这样做，是因为执行合并的程序必须确保 phandle 编号是连续和唯一的。
在 [part1.3 第 1.3 节] 中说 "原始标签不会出现在编译输出中"，但使用 -@ 开关时并非如此。相反，每个标签都会在 __symbols__ 节点中产生一个属性，将标签映射到路径，这与 aliases 节点完全相同。事实上，这种机制非常相似，以至于在解析符号时，如果没有 __symbols__ 节点，Raspberry Pi 载入器也会搜索 "aliases "节点。这曾一度很有用，因为提供足够的别名可以让非常旧版本的 dtc 被用来构建基础 DTB 文件，但幸运的是，这已经成为历史了。
Device Trees参数
为了避免需要大量的Device Treesoverlay，并减少用户修改外围设备DTS文件的需要，树莓派加载器支持一项新功能——Device Trees参数。这支持使用命名参数对DT进行微小的更改，类似于内核模块从 modprobe 和内核命令行接收参数的方式。参数可以通过基本 DTB 和 overlay 来引出，包括HAT overlay。
在DTS中通过向根添加一个 __overrides__ 节点来定义参数。它包含属性，其名称是所选参数名称，其值是一个序列，包括目标节点的phandle（对标签的引用）和指示目标属性的字符串；支持字符串、整数（单元格）和布尔属性。
字符串参数（String parameters）
字符串参数是这样声明的：
name = <&label>,"property";
其中 label 和 property 被合适的值替换。字符串参数可以修改其目标属性。
请注意，名为 status 的属性会被特殊处理；非 0/true/yes/on 的值会转换为字符串 "okay"，而 0/false/no/off 则会变成 "disabled"。
整数参数（Integer parameters）
整数参数声明如下：
name = <&label>,"property.offset"; // 8-bit
name = <&label>,"property;offset"; // 16-bit
name = <&label>,"property:offset"; // 32-bit
name = <&label>,"property#offset"; // 64-bit这里， label , property 和 offset 由合适的值代替；偏移量以字节为单位指定，相对于属性的起点（默认为十进制），前面的分隔符决定了参数的大小。与以前的实现不同，整数参数可以指向不存在的属性或超出现有属性末尾的偏移量。
布尔参数（Boolean parameters）
Device Trees将布尔值编码为零长度属性；如果存在，则该属性为真，否则为假。它们是这样定义的：
boolean_property; // Set 'boolean_property' to true如果不定义一个属性，该属性就会被赋值为 false。布尔参数也是这样声明的，用合适的值代替 label 和 property 占位符：
name = <&label>,"property?";反转布尔值在以与常规布尔值相同的方式应用输入值之前反转输入值；它们的声明类似，但使用 ！ 表示反转：
name = <&label>,"<property>!";布尔参数可以创建或删除属性，但不能删除基础 DTB 中已存在的属性。
字节字符串参数（Byte string parameters）
字节字符串属性是任意的字节序列，如 MAC 地址。它们接受十六进制字节字符串，字节之间可以有冒号，也可以没有冒号。
mac_address = <ðernet0>,"local_mac_address[";选择 [ 来匹配声明字节字符串的DT语法：
local_mac_address = [aa bb cc dd ee ff];
具有多个目标的参数（Parameters with multiple targets）
在某些情况下，在设备树的多个位置设置相同的值会很方便。与创建多个参数的笨拙方法相比，我们可以通过串联的方式为单个参数添加多个目标，如下所示：
__overrides__ {
gpiopin = <&w1>,"gpios:4",
<&w1_pins>,"brcm,pins:0";
...
};（示例取自 w1-gpio overlay）
|
Note
|
甚至可以用一个参数针对不同类型的属性。您可以合理地将 "enable "参数连接到 "status "字符串、包含 0 或 1 的单元格以及适当的布尔属性。 |
文字赋值（Literal assignments）
DT 参数机制允许对同一参数的多个目标进行修补，但由于必须将相同的值写入所有位置（格式转换和反布尔值的否定除外），因此实用性受到限制。增加嵌入式字面赋值后，一个参数可以写入任意值，与用户提供的参数值无关。
赋值在声明的末尾出现，并由 = 表示：
str_val = <&target>,"strprop=value"; // 1
int_val = <&target>,"intprop:0=42" // 2
int_val2 = <&target>,"intprop:0=",<42>; // 3
bytes = <&target>,"bytestr[=b8:27:eb:01:23:45"; // 4第1、2和4行相当明显，但第3行更有趣，因为该值显示为整数（单元格）值。DT编译器在编译时计算整数表达式，这可能很方便（特别是如果使用宏值），但单元格也可以包含对标签的引用：
//强制LED在内部GPIO控制器上使用GPIO。
exp_led = <&led1>,"gpios:0=",<&gpio>,
<&led1>,"gpios:4";使用overlay时，标签通常根据基础 DTB 进行解析。最好将多部分参数拆分到多行，这样更容易阅读 - 随着单元格值分配的增加，这变得更加必要。
请注意，除非应用参数，否则参数不起任何作用 - 查找表中的默认值会被忽略，除非在使用参数名称时没有赋值。
查找表（Lookup tables）
查找表允许在使用参数输入值之前对其进行转换。它们充当关联数组，就像switch/case语句一样：
phonetic = <&node>,"letter{a=alpha,b=bravo,c=charlie,d,e,='tango uniform'}";
bus = <&fragment>,"target:0{0=",<&i2c0>,"1=",<&i2c1>,"}";一个没有 =value 的键表示使用该键作为值，一个前面没有键的 = 表示在没有匹配的情况下使用默认值，用逗号（或任何地方的空 key=value 对）开始或结束的列表表示应使用未匹配的输入值，否则，找不到匹配的值出现错误。
|
Note
|
单元格整数值后的表格字符串中的逗号分隔符是隐式的，显式添加逗号分隔符会产生空对（见上文）。 |
|
Note
|
由于查找表对输入值进行操作，而字面赋值会忽略输入值，因此无法将两者结合起来—查找声明中结尾 } 后的字符会被视为错误。
|
Overlay/fragment 参数（Overlay/fragment parameters）
所描述的DT参数机制有许多限制，包括缺乏创建整数数组的简单方法，以及无法创建新节点。克服其中一些限制的一种方法是有条件地包含或去除某些片段。
通过将 __overlay__ 节点重命名为 __dormant__ ，可以将片段从最终合并过程中排除（禁用）。参数声明语法已扩展为允许否则非法的零目标phandle指示以下字符串包含片段或overlay范围内的操作。到目前为止，已经实现了四个操作：
+<n> // Enable fragment <n>
-<n> // Disable fragment <n>
=<n> // Enable fragment <n> if the assigned parameter value is true, otherwise disable it
!<n> // Enable fragment <n> if the assigned parameter value is false, otherwise disable it例子：
just_one = <0>,"+1-2"; // Enable 1, disable 2
conditional = <0>,"=3!4"; // Enable 3, disable 4 if value is true,
// otherwise disable 3, enable 4.i2c-rtc overlay 使用这种技术。
特殊属性（Special properties）
有几个属性名在被参数锁定后会得到特殊处理。其中一个你可能已经注意到了-- status --会将布尔值转换为 okay 为真、 disabled 为假。
赋值给 bootargs 属性会追加而不是覆盖它—这就是如何将设置添加到内核命令行的方法。
reg 属性用于指定设备地址—内存映射硬件块的位置、I2C 总线上的地址等。子节点的名称应以十六进制地址限定，并使用 @ 作为分隔符：
bmp280@76 {
reg = <0x77>;
...
};分配给 reg 属性时，父节点名称的地址部分将被替换为分配的值。这可用于防止多次使用相同 overlay 时节点名称冲突 — i2c-gpio overlay 就使用了这种方法。
name 属性是一个伪属性—它不应该出现在 DT 中，但对其赋值可以改变父节点的名称。与 reg 属性一样，该属性可用于为节点赋予唯一的名称。
overlay 映射文件（The overlay map file）
基于BCM2711 SoC设计的Raspberry Pi 4带来了许多变化；其中一些变化是额外的接口，一些是对现有接口的修改（或删除）。有专门为Raspberry Pi 4设计的新 overlay， 他们在旧硬件上没有意义，例如支持新SPI、I2C和通用异步收发设备接口的overlay，老的overlay将无法工作，即使它们仍然控制着新设备上相关的功能。
因此，我们需要一种方法，为硬件不同的多个平台量身定制 overlay。要在单个 .dtbo 文件中支持所有平台，就需要大量使用隐藏（"休眠"）片段，并改用按需符号解析机制，这样就不会因为缺少不需要的符号而导致故障。一个更简单的解决方案是根据当前平台，添加一个将 overlay 名称映射到多个实现文件之一的工具。
overlay 映射是固件在启动时加载的文件。它以DTS源代码格式 - overlay_map.dts 编写，编译为 overlay_map.dtb 并存储在 overlays 目录中。
这是当前映射文件的摘录（详见 完整文件）：
/ {
disable-bt {
bcm2835;
bcm2711;
bcm2712 = "disable-bt-pi5";
};
disable-bt-pi5 {
bcm2712;
};
uart5 {
bcm2711;
};
pi3-disable-bt {
renamed = "disable-bt";
};
lirc-rpi {
deprecated = "use gpio-ir";
};
};每个节点都有一个需要特殊处理的overlay的名称。每个节点的属性要么是平台名称，每个节点都有一个需要特殊处理的overlay名称。每个节点的属性要么是平台名称，要么是少数特殊指令之一。overlay ，map支持以下平台名称：
-
bcm2835用于所有围绕 BCM2835、BCM2836、BCM2837 和 RP3A0 SoC 构建的 Raspberry Pis -
用于 Raspberry Pi 4B、CM4、CM4S 和 Pi 400 的
bcm2711 -
用于 Raspberry Pi 5、CM5 和 Pi 500 的
bcm2712
没有值的平台名称（空属性）表示当前 overlay 与平台兼容；例如， uart5 与 bcm2711 平台兼容。平台的非空值是替代请求 overlay 的替代 overlay 的名称；在BCM2712上使用 disable-bt 会加载 disable-bt-pi5 。overlay 节点中未包含的任何平台都与该 overlay 不兼容。映射文件中未提及的任何 overlay 都假定与所有平台兼容。
第二个示例节点 "disable-bt-pi5 "可以从 "disable-bt "的内容中推断出来，但这种智能是用于构建文件，而不是解释文件。
uart5 overlay 仅在BCM2711上有意义。
如果平台未列出 overlay ，则可能适用以下特殊指令之一：
-
renamed指令指示 overlay 的新名称（应与原名称基本兼容），但也会出现重命名记录。 -
deprecated "指令包含一条简短的解释性错误信息，该信息将在常用前缀
overlay '...' is deprecated:之后记录。
重命名和特定平台的链式实现是可能的，但要注意避免循环！
请记住：只需要列出异常-没有 overlay 节点意味着默认文件应用于所有平台。
在 Debugging 中介绍了如何从固件获取诊断消息。
dtoverlay 和 dtmerge 实用程序已扩展为支持映射文件：
-
dtmerge从基础 DTB 中的兼容字符串中提取平台名称。 -
dtoverlay从/proc/device-tree中的实时设备树中读取兼容字符串，但也可以使用-p选项提供另一个平台名称（对于在不同平台上的模拟运行非常有用）。
它们都向STDERR发送错误、警告和任何调试输出。
示例
以下是不同类型属性的一些示例，以及修改它们的参数：
/ {
fragment@0 {
target-path = "/";
__overlay__ {
test: test_node {
string = "hello";
status = "disabled";
bytes = /bits/ 8 <0x67 0x89>;
u16s = /bits/ 16 <0xabcd 0xef01>;
u32s = /bits/ 32 <0xfedcba98 0x76543210>;
u64s = /bits/ 64 < 0xaaaaa5a55a5a5555 0x0000111122223333>;
bool1; // Defaults to true
// bool2 defaults to false
mac = [01 23 45 67 89 ab];
spi = <&spi0>;
};
};
};
fragment@1 {
target-path = "/";
__overlay__ {
frag1;
};
};
fragment@2 {
target-path = "/";
__dormant__ {
frag2;
};
};
__overrides__ {
string = <&test>,"string";
enable = <&test>,"status";
byte_0 = <&test>,"bytes.0";
byte_1 = <&test>,"bytes.1";
u16_0 = <&test>,"u16s;0";
u16_1 = <&test>,"u16s;2";
u32_0 = <&test>,"u32s:0";
u32_1 = <&test>,"u32s:4";
u64_0 = <&test>,"u64s#0";
u64_1 = <&test>,"u64s#8";
bool1 = <&test>,"bool1!";
bool2 = <&test>,"bool2?";
entofr = <&test>,"english",
<&test>,"french{hello=bonjour,goodbye='au revoir',weekend}";
pi_mac = <&test>,"mac[{1=b8273bfedcba,2=b8273b987654}";
spibus = <&test>,"spi:0[0=",<&spi0>,"1=",<&spi1>,"2=",<&spi2>;
only1 = <0>,"+1-2";
only2 = <0>,"-1+2";
enable1 = <0>,"=1";
disable2 = <0>,"!2";
};
};对于更多的例子，大量的 overlay 源文件被托管在 Raspberry PiLinuxGitHub存储库 中。
导出标签（Export labels）
固件中的 dtoverlay 处理以及使用 "dtoverlay" 工具的运行时 dtoverlay 应用，都将 dtoverlay 中定义的标签视为该 dtoverlay 的私有标签。这避免了为标签创建全局唯一名称（使标签保持简短），并允许多次使用同一 dtoverlay 而不发生冲突（前提是使用了一些技巧 - 请参阅 Special properties ）。
有时，创建带有一个overlay的标签并从另一个overlay使用它是非常有用的。自2020年2月14日以来发布的固件能够将某些标签声明为全局标签 - __exports__ 节点：
...
public: ...
__exports__ {
public; // Export the label 'public' to the base DT
};
};应用此 dtoverlay 时，加载程序会删除除已导出符号之外的所有符号，在本例中为 public ，并重写路径以使其相对于包含标签的片段的目标。在此之后加载的 dtoverlay 可以引用 &public 。
在树莓派上使用Device Trees（Using Device Trees on Raspberry Pi）
DTB、overlays 和 config.txt（DTBs, overlays and config.txt）
在 Raspberry Pi 上，加载器（"start.elf "映像之一）的工作是将overlay层与适当的基础设备树结合起来，然后将完全解析的设备树传递给内核。基本设备树与 start.elf 一起位于 FAT 分区（Linux 中为 /boot/firmware/ ）中，名为 bcm2711-rpi-4-b.dtb、 bcm2710-rpi-3-b-plus.dtb 等。请注意，某些型号（3A+、A、A+）将分别使用 "b "对应的型号（3B+、B、B+）。这种选择是自动的，允许在各种设备中使用相同的 SD 卡映像。
|
Note
|
DT 和 ATAG 是互斥的，将 DT blob 传递给无法理解它的内核会导致启动失败。固件将始终尝试加载 DT 并将其传递给内核，因为自 rpi-4.4.y 以来的所有内核如果没有 DTB 就无法运行。您可以通过在 config.txt 中添加 device_tree= 来覆盖此设置，这会强制使用 ATAG，这对于简单的裸机内核非常有用。
|
加载器现在支持使用 bcm2835_defconfig 进行构建，它选择上游的 BCM2835 支持。此配置将构建 bcm2835-rpi-b.dtb 和 bcm2835-rpi-b-plus.dtb 。如果这些文件与内核一起复制，则加载器将默认尝试加载其中一个 DTB。
为了管理Device Trees和 overlays，加载程序支持许多 config.txt 指令：
dtoverlay=acme-board
dtparam=foo=bar,level=42加载程序会在固件分区中查找 overlays/acme-board.dtbo ，Raspberry Pi OS 将其安装在 /boot/firmware/ 上。然后它将搜索参数 foo 和 level ，并为它们分配指示的值。
加载程序还将搜索带有编程 EEPROM 的附加 HAT，并从那里加载支持 overlay - 直接加载或按名称从 overlays 目录中加载；这无需任何用户干预。
有多种方法可以判断内核正在使用Device Trees：
-
启动过程中的内核信息 "Machine model:（机器型号：）"具有特定板卡的值，如 "Raspberry Pi 2 Model B"，而不是 "BCM2709"。
-
存在
/proc/device-tree，其中包含的子目录和文件与 DT 的节点和属性完全一致。
使用Device Trees，内核将自动搜索并加载支持已启用设备的模块。因此，通过为设备创建适当的 DT overlay，您可以节省设备用户编辑 /etc/modules 的时间；所有配置都放在 config.txt 中，对于 HAT，甚至该步骤也是不必要的。但请注意，分层模块（例如 i2c-dev ）仍需要指明加载。
另一方面，由于平台设备只有在 DTB 请求时才会创建，因此不再需要将以前由于板支持代码中定义的平台设备而加载的模块列入黑名单。事实上，当前的 Raspberry Pi OS 镜像不附带黑名单文件（某些 WLAN 设备除外，因为有多个驱动程序可用）。
DT 参数（DT parameters）
如上所述，DT 参数是一种方便对设备配置进行细微更改的方法。当前基础 DTB 支持启用和控制板载音频、I2C、I2S 和 SPI 接口的参数，而无需使用专用 overlay。在使用中，参数如下所示：
dtparam=audio=on,i2c_arm=on,i2c_arm_baudrate=400000,spi=on|
Note
|
可以在同一行上放置多个分配，但请确保不超过 80 个字符的限制。 |
如果您的overlay定义了一些参数，则可以在后续行中指定这些参数，如下所示：
dtoverlay=lirc-rpi
dtparam=gpio_out_pin=16
dtparam=gpio_in_pin=17
dtparam=gpio_in_pull=down…或附加到 overlay 行，如下所示：
dtoverlay=lirc-rpi,gpio_out_pin=16,gpio_in_pin=17,gpio_in_pull=downdtoverlay 参数的作用域只到下一个 dtoverlay 被加载为止。如果 dtoverlay 和基本 DTB 都导出了同名参数，则 dtoverlay 中的参数优先；建议避免这样做。要使用基础 DTB 导出的参数，请使用以下命令结束当前的 overlay 作用域：
dtoverlay=特定于电路板的标签和参数（Board-specific labels and parameters）
Raspberry Pi 板有两个 I2C 接口。它们名义上是分开的：一个用于 ARM，一个用于 VideoCore（GPU）。在几乎所有型号上， i2c1 属于 ARM，而 i2c0 属于 VC，它用于控制摄像头和读取 HAT EEPROM。但是，B 型有两个早期版本，它们的角色互换了。
为了能够在所有 Raspberry Pi 上使用一组 overlay 和参数，固件创建了一些特定于板的 DT 参数。这些是：
i2c/i2c_arm i2c_vc i2c_baudrate/i2c_arm_baudrate i2c_vc_baudrate
这些是 i2c0、 i2c1、 i2c0_baudrate 和 i2c1_baudrate 的别名。建议只在确实需要时才使用 i2c_vc 和 i2c_vc_baudrate - 例如，在对 HAT EEPROM 编程时（最好使用软件 I2C 总线，并使用 i2c-gpio overlay）。启用 i2c_vc 会导致 Raspberry Pi 摄像头或 Raspberry Pi 触摸显示器无法正常工作。
对于编写 overlay 的人来说，同样的混淆现象也适用于I2C DT节点上的标签。因此，您应该编写：
fragment@0 {
target = <&i2c_arm>;
__overlay__ {
status = "okay";
};
};任何使用数字变体的 overlay 都将被修改为使用新的别名。
HAT 和 Device Trees
Raspberry Pi HAT是一个带有嵌入式EEPROM的附加板，专为具有40引脚排针的Raspberry Pi设计。EEPROM包括启用电路板所需的所有 DT overlay （或从文件系统加载的 overlay 名称），此 overlay 还可以引出参数。
在加载基础 DTB 之后，固件会自动加载 HAT overlay ，因此在加载任何其他 overlay 之前，或者在使用 dtoverlay= 结束 overlay 范围之前，可以访问其参数。如果出于某种原因您想禁止加载 HAT overlay ，请将 dtoverlay= 放在所有 dtoverlay 或 dtparam 指令之前。
动态Device Trees（Dynamic Device Tree）
从 Linux 4.4 开始，树莓派内核支持overlay和参数的动态加载。兼容内核管理应用于 基础 DTB 之上的 overlay 堆栈。更改会立即反映在 /proc/device-tree 中，并可能使模块被加载，平台设备被创建和销毁。
上面 堆栈 这个词的使用很重要—— overlay 只能在堆栈顶部添加和删除；更改堆栈中下面的东西需要首先删除它上面的所有东西。
有一些用于管理 overlay 的新命令：
dtoverlay 命令
dtoverlay 是一个命令行实用程序，它在系统运行时加载和删除 overlay ，以及列出可用的 overlay 并显示它们的帮助信息。
使用 dtoverlay -h 获取使用信息：
Usage:
dtoverlay <overlay> [<param>=<val>...]
Add an overlay (with parameters)
dtoverlay -D [<idx>] Dry-run (prepare overlay, but don't apply -
save it as dry-run.dtbo)
dtoverlay -r [<overlay>] Remove an overlay (by name, index or the last)
dtoverlay -R [<overlay>] Remove from an overlay (by name, index or all)
dtoverlay -l List active overlays/params
dtoverlay -a List all overlays (marking the active)
dtoverlay -h Show this usage message
dtoverlay -h <overlay> Display help on an overlay
dtoverlay -h <overlay> <param>.. Or its parameters
where <overlay> is the name of an overlay or 'dtparam' for dtparams
Options applicable to most variants:
-d <dir> Specify an alternate location for the overlays
(defaults to /boot/firmware/overlays or /flash/overlays)
-v Verbose operation
与 config.txt 等效项不同， overlay 的所有参数都必须包含在同一个命令行中 - dtparam 命令仅用于基础 DTB 的参数。
更改内核状态（添加和删除内容）的命令需要root权限，因此您可能需要在命令前加上 sudo 。只有运行时应用的overlay和参数可以卸载 - 固件使用的 overlay 或参数会被 "嵌入"，因此它不会被 dtoverlay 列出，也不能被删除。
dtparam 命令
dtparam 创建并加载一个 overlay ，其效果与在 config.txt 中使用 dtparam 指令基本相同。在用法上，它与称为 - 的 dtoverlay 大致相同，但也有一些不同之处： dtparam 会列出基本 DTB 所有已知参数的帮助信息。dtparam 命令的帮助仍可使用 ` dtparam -h 。在指明要删除的参数时，只能使用索引号（而不能使用名称）。并非所有 Linux 子系统都会对运行时添加的设备做出响应—I2C、SPI 和声音设备可以工作，但有些则不行。
编写支持运行时的 overlay 的指南
设备对象的创建或删除由添加或删除节点触发，或者由节点状态从禁用更改为启用触发，反之亦然。没有 status 属性意味着节点已启用。
不要在片段中创建会覆盖基础 DTB 中现有节点的节点，内核会重命名新节点，使其独一无二。如果要更改现有节点的属性，请创建一个针对该节点的片段。
ALSA 不会阻止其编解码器和其他组件在使用中被卸载。如果删除的编解码器仍被声卡使用，那么删除 overlay 就会导致内核异常。实验发现，设备的删除顺序与 overlay 中片段的删除顺序相反，因此将声卡的节点放在组件的节点之后，可以实现有序关闭。
注意事项
在运行时加载 overlay 是内核的最新功能，在撰写本报告时，还没有从用户空间加载 overlay 的公认方法。通过将这一机制的细节隐藏在命令之后，用户可以避免在不同的内核接口标准化后发生变化。
-
有些 overlay 在运行时比其他 overlay 更好用。设备树的部分内容只在启动时使用，使用 overlay 更改这些内容不会产生任何影响。
-
应用或删除某些 overlay 可能会导致意想不到的行为，因此应谨慎操作。这也是需要 "sudo "的原因之一。
-
如果有东西正在使用 ALSA，卸载 ALSA 卡的 overlay 可能会导致停滞，LXPanel 音量滑块插件就有这种效果。为了能够移除声卡的 overlay ，
lxpanelctl工具新增了两个选项--alsastop和alsastart- 它们分别在加载或卸载 overlay 之前和之后从辅助脚本dtoverlay-pre和dtoverlay-post中调用。 -
移除 overlay 不会导致已加载模块被卸载，但可能会导致某些模块的引用计数降为零。运行两次
rmmod -a会导致卸载未使用的模块。 -
必须以相反的顺序移除 overlay 。命令允许你移除较早的 overlay ，但所有中间的 overlay 都会被移除并重新应用，这可能会产生意想不到的后果。
-
只探测设备树顶层的节点和总线节点的子节点。对于运行时添加的节点，还有一个限制条件，即总线必须注册以接收添加和删除子节点的通知。不过，也有一些例外情况会打破这一规则并造成混乱：内核会明确扫描整个树中的某些设备类型（时钟和中断控制器是两个主要类型），以便（对于时钟）提前初始化和/或（对于中断控制器）按特定顺序初始化。这种搜索机制只在启动过程中进行，因此对运行时由 overlay 添加的节点不起作用。因此，建议 overlay 将固定时钟节点放在树的根部，除非能保证 overlay 在运行时不会被使用。
支持的 overlay 和参数
有关支持的overlay和参数列表，请参阅 /boot/firmware/overays 中 .dtbo 文件旁边的 README 文件。它会及时添加和更改保持最新的状态。
固件参数
固件使用特殊的 /chosen 节点在引导加载程序和/或固件与操作系统之间传递参数。除非另有说明，否则每个属性都存储为 32 位整数。
overlay_prefix-
(string)
config.txt选择的 overlay_prefix 字符串。 os_prefix-
(string) 由
config.txt选取的 os_prefix 字符串。 rpi-boardrev-ext-
扩展电路板修订代码来自 OTP 行 33。
rpi-country-code-
PiWiz 使用的国家代码。仅限 Raspberry Pi 400。
rpi-duid-
(string) 仅限 Raspberry Pi 5。PCB 上 QR 码的字符串表示。
Common bootloader properties /chosen/bootloader
除非另有说明，否则每个属性都存储为 32 位整数。
boot-mode-
用于加载内核的启动模式。从此查看 BOOT_ORDER 支持的值。
partition-
启动时使用的分区号。如果加载的是
boot.imgramdisk，则指的是内存盘加载的分区，而不是内存盘中的分区号。 pm_rsts-
启动时
PM_RSTS寄存器的值。 tryboot-
如果启动时设置了
tryboot标志，则设为1。
Power supply properties /chosen/power
仅限 Raspberry Pi 5。除非另有说明，否则每个属性都存储为 32 位整数。
max_current-
电源可提供的最大电流（毫安）。固件会报告 USB-C、USB-PD 或 PoE 接口指示的值。对于台式电源（例如连接到 GPIO 头），在引导加载程序配置中定义
PSU_MAX_CURRENT，以指示电源电流能力。 power_reset-
仅限 Raspberry Pi 5。表明 PMIC 复位原因的位字段。
| 位 | 原因 |
|---|---|
0 |
过电压 |
1 |
欠压 |
2 |
温度过高 |
3 |
启用信号 |
4 |
看门狗 |
rpi_power_supply-
(two 32-bit integers) Raspberry Pi 27W 官方电源的 USB VID 和产品 VDO（如果已连接）。
usb_max_current_enable-
如果 USB 端口电流限制器在启动过程中设置为低限值，则为零；如果启用了高限值，则为非零。如果电源要求最大电流为 5A 或在
config.txt中强制设置了usb_max_current_enable=1，则会自动启用高电平。 usb_over_current_detected-
如果 USB 启动期间发生 USB 过流事件，则为非零。
usbpd_power_data_objects-
(binary blob containing multiple 32-bit integers) 在 USB-PD 协商过程中，引导加载程序接收到的原始二进制 USB-PD 对象（仅限固定电源）。要捕获这些信息以用于错误报告，请运行
hexdump -C /proc/device-tree/chosen/power/usbpd_power_data_objects。
格式由 https://usb.org/document-library/usb-power-delivery [USB Power Delivery] 规范定义。
BCM2711 and BCM2712 specific bootloader properties /chosen/bootloader
以下属性针对 BCM2711 和 BCM2712 SPI EEPROM 引导加载程序。除非另有说明，否则每个属性都存储为 32 位整数。
build_timestamp-
EEPROM 引导加载程序的 UTC 生成时间。
capabilities-
该位字段描述当前引导加载程序支持的功能。在引导加载程序 EEPROM 配置中启用某项功能（如 USB 启动）之前，可以用它来检查该功能是否受支持。
| 位 | 功能 |
|---|---|
0 |
USB boot 使用VLI USB主机控制器 |
1 |
|
2 |
TRYBOOT_A_B 模式 |
3 |
|
4 |
USB boot 使用BCM2711 USB主机控制器 |
5 |
|
6 |
|
7 |
update_timestamp-
由
rpi-eeprom-update设置的 UTC 更新时间戳。 signed-
如果启用了安全启动，该位字段将不为零。各个位表示当前的安全启动配置。
| 位 | 描述 |
|---|---|
0 |
|
1 |
保留 |
2 |
ROM开发密钥已被撤销，参见 revoke_devkey。 |
3 |
客户公钥摘要已写入OTP，参见 program_pubkey。 |
4…31 |
保留 |
version-
(string) 引导加载程序的 Git 版本字符串。
BCM2711和BCM2712 USB启动属性 /chosen/bootloader/usb
如果系统是从 USB 启动的，则会定义以下属性。这些属性可用于唯一标识 USB 启动设备。每个属性都存储为 32 位整数。
usb-version-
USB 主要协议版本（2 或 3）。
route-string-
设备的 USB 路由字符串标识符，由 USB 3.0 规范定义。
root-hub-port-number-
启动设备连接的根集线器端口号，可能通过其他 USB 集线器连接。
lun-
大容量存储设备的逻辑单元编号。
NVMEM nodes
固件通过 NVMEM 子系统提供引导加载程序 EEPROM 部分的只读内存副本。
每个区域在 /sys/bus/nvmem/devices/ 下显示为一个 NVMEM 设备，在 /sys/firmware/devicetree/base/aliases 下有一个命名的别名。
从 rpi-eeprom-update 读取 NVMEM 模式的 shell 脚本代码示例：
blconfig_alias="/sys/firmware/devicetree/base/aliases/blconfig"
blconfig_nvmem_path=""
if [ -f "${blconfig_alias}" ]; then
blconfig_ofnode_path="/sys/firmware/devicetree/base"$(strings "${blconfig_alias}")""
blconfig_ofnode_link=$(find -L /sys/bus/nvmem -samefile "${blconfig_ofnode_path}" 2>/dev/null)
if [ -e "${blconfig_ofnode_link}" ]; then
blconfig_nvmem_path=$(dirname "${blconfig_ofnode_link}")
fi
fi
fiblconfig-
别名，指的是存储引导加载程序 EEPROM 配置文件副本的 NVMEM 设备。
blpubkey-
别名，该别名指向一个 NVMEM 设备，该设备以二进制格式存储引导加载器 EEPROM 公钥（如果定义了）的副本。 rpi-bootloader-key-convert实用程序可用于将数据转换为 PEM 格式，以便与 OpenSSL 配合使用。
更多信息，请参阅 secure-boot。
故障排除
调试
加载程序将跳过丢失的 overlay 和错误参数，但如果出现严重错误，例如丢失或损坏的基础 DTB 或失败的 overlay 合并，则加载程序将回退到非DT引导。如果发生这种情况，或者您的设置没有按您的预期运行，则值得检查加载程序的警告或错误：
$ sudo vclog --msg可以通过将 dtdebug=1 添加到 config.txt 来启用额外的调试。
您可以导出DT当前状态的可读表示，如下所示：
$ dtc -I fs /proc/device-tree这对于查看将 overlay 合并到底层树上的效果很有用。
如果内核模块未按预期加载，请检查它们是否未在 /etc/modprobe.d/raspi-Blacklist.conf 中列入黑名单；使用Device Trees时不需要列入黑名单。如果没有显示任何异常，您还可以通过搜索 /lib/modules/<version>/modules.alias 以获取 compatible 值来检查模块是否导出了正确的别名。否则，您的驱动程序可能会丢失：
.of_match_table = xxx_of_match,
或：
MODULE_DEVICE_TABLE(of, xxx_of_match);
否则， depmod 就会失败，或者更新的模块尚未安装在目标文件系统上。
使用 dtmerge、dtdiff 和 ovmerge 测试 overlay
除了 dtoverlay 和 dtparam 命令之外，还有一个用于将 overlay 应用于DTB的实用程序- dtmerge 。要使用它，您首先需要获取您的基础 DTB ，可以通过以下两种方式之一获得：
从 /proc/device-tree 中的实时DT状态生成它：
$ dtc -I fs -O dtb -o base.dtb /proc/device-tree这将包括您到目前为止应用的任何 overlay 和参数，无论是在 config.txt 中还是在运行时加载它们，这可能是您想要的，也可能不是您想要的。或者：
从 /boot/firmware/ 中的源DTB复制它。这不包括 overlay 和参数，但也不包括固件的任何其他修改。为了允许测试所有 overlay ， dtmerge 实用程序将创建一些特定于板的别名（ i2c_arm 等），但这意味着合并的结果将包含比您预期的更多与原始DTB的差异。解决这个问题的方法是使用dt合并来进行复制：
$ dtmerge /boot/firmware/bcm2710-rpi-3-b.dtb base.dtb -（ - 表示不存在 overlay 名称）。
您现在可以尝试应用 overlay 或参数：
$ dtmerge base.dtb merged.dtb - sd_overclock=62
$ dtdiff base.dtb merged.dtb哪个将返回：
--- /dev/fd/63 2016-05-16 14:48:26.396024813 +0100
+++ /dev/fd/62 2016-05-16 14:48:26.396024813 +0100
@@ -594,7 +594,7 @@
};
sdhost@7e202000 {
- brcm,overclock-50 = <0x0>;
+ brcm,overclock-50 = <0x3e>;
brcm,pio-limit = <0x1>;
bus-width = <0x4>;
clocks = <0x8>;您还可以比较不同的 overlay 或参数。
$ dtmerge base.dtb merged1.dtb /boot/firmware/overlays/spi1-1cs.dtbo
$ dtmerge base.dtb merged2.dtb /boot/firmware/overlays/spi1-2cs.dtbo
$ dtdiff merged1.dtb merged2.dtb得到：
--- /dev/fd/63 2016-05-16 14:18:56.189634286 +0100
+++ /dev/fd/62 2016-05-16 14:18:56.189634286 +0100
@@ -453,7 +453,7 @@
spi1_cs_pins {
brcm,function = <0x1>;
- brcm,pins = <0x12>;
+ brcm,pins = <0x12 0x11>;
phandle = <0x3e>;
};
@@ -725,7 +725,7 @@
#size-cells = <0x0>;
clocks = <0x13 0x1>;
compatible = "brcm,bcm2835-aux-spi";
- cs-gpios = <0xc 0x12 0x1>;
+ cs-gpios = <0xc 0x12 0x1 0xc 0x11 0x1>;
interrupts = <0x1 0x1d>;
linux,phandle = <0x30>;
phandle = <0x30>;
@@ -743,6 +743,16 @@
spi-max-frequency = <0x7a120>;
status = "okay";
};
+
+ spidev@1 {
+ #address-cells = <0x1>;
+ #size-cells = <0x0>;
+ compatible = "spidev";
+ phandle = <0x41>;
+ reg = <0x1>;
+ spi-max-frequency = <0x7a120>;
+ status = "okay";
+ };
};
spi@7e2150C0 {https://github.com/raspberrypi/utils[Utils] 存储库包括另一个DT实用程序- `ovmerge` 。与 `dtmerge` 不同， `ovmerge` 结合了文件并以源代码形式应用overlay。因为overlay永远不会被编译，所以标签会被保留，结果通常更具可读性。它还具有许多其他技巧，例如列出文件包含顺序的能力。
强制使用特定Device Trees
如果您有默认 DTB 不支持的特殊需求，或者您只是想尝试编写自己的 DTB，您可以告诉加载器加载类似这样的备用 DTB 文件：
device_tree=my-pi.dtb禁用Device Trees使用
Raspberry PiLinux内核中需要使用Device Trees。对于裸机和其他操作系统，可以通过添加以下内容来禁用DT使用：
device_tree=到 config.txt 。
快捷方式和语法变体
加载器理解一些快捷方式：
dtparam=i2c_arm=on
dtparam=i2s=on可以缩短为：
dtparam=i2c,i2s（ i2c 是 i2c_arm 的别名，假设为 =on ）。它仍然接受长格式版本： device_tree_overlay 和 device_tree_param 。
config.txt 中可用的其他 DT 命令
device_tree_address:： 用于更改固件加载设备树（非 dt-blob）的地址。默认情况下，固件会选择一个合适的位置。
device_tree_end:： 为加载的设备树设置（排他性）限制。默认情况下，设备树可以增长到可用内存的尽头，这几乎肯定是需要的。
dtdebug:： 如果非零，则为固件的设备树处理开启一些额外的日志记录。
enable_uart:： 启用主/控制台 UART（Raspberry Pi 3、4、400、Zero W 和 Zero 2 W 上为 ttyS0，其他情况下为 ttyAMA0 - 除非与 miniuart-bt 等覆层交换）。如果主 UART 为 ttyAMA0，则`enable_uart`默认为 1（启用），否则默认为 0（禁用）。这是因为必须阻止内核频率发生变化，否则 ttyS0 将无法使用，因此 enable_uart=1 意味着 core_freq=250（除非 force_turbo=1）。在某些情况下，这会影响性能，因此默认关闭。
overlay_prefix:： 指定加载覆盖层的子目录/前缀—默认为 "overlay/"。注意尾部的"/"。如果需要，你可以在最后的"/"后面添加一些内容，为每个文件添加一个前缀，不过这不大可能需要。
DT可以控制更多端口。有关详细信息，请参阅 section 3。
进一步的帮助
如果您已经阅读了本文档，但仍未找到 "设备树 "问题的答案，我们可以提供帮助。通常可以在 Raspberry Pi 论坛上找到作者，尤其是 Device Tree 论坛。
更改默认引脚配置
在 GitHub 上修改
|
Note
|
已弃用通过用户提供的设备树blob自定义默认引脚配置。 |
引导过程中的设备引脚
在启动序列期间，GPIO引脚会执行各种操作。
在软重置时，除默认拉动外，其他程序相同，默认拉动仅在开机重置时应用。
整个过程可能需要几秒钟。在此期间，GPIO 引脚可能不会处于所连接外设（如 dt-blob.bin 或 config.txt 中定义）预期的状态。由于不同的 GPIO 引脚有不同的默认拉动方式，因此应为外设执行以下*项之一：
-
选择一个 GPIO 引脚，该引脚在复位时按外设的要求默认拉动
-
延迟外设的启动时间，直至操作完成
-
添加适当的上拉/下拉电阻器
提供自定义设备树blob
为了将设备树源（ .dts ）文件编译为设备树blob（ .dtb ）文件，必须通过运行 sudo apt installdevice-tree-compiler 来安装设备树编译器。然后可以如下使用 dtc 命令：
$ sudo dtc -I dts -O dtb -o /boot/firmware/dt-blob.bin dt-blob.dts类似地，如果需要，可以将 .dtb 文件转换回 .dts 文件。
$ dtc -I dtb -O dts -o dt-blob.dts /boot/firmware/dt-blob.bin
dt-blob 的部分
dt-blob.bin用于在引导时配置二进制blob（VideoCore）。Linux内核当前未使用它。dt-blob可以配置所有版本的Raspberry Pi（包括Compute Module）以使用替代设置。以下部分在dt-blob中有效：
pins_*
基于特定的Raspberry Pi型号，有许多单独的 pins_* 部分，即：
-
pins_rev1： Rev1 引脚设置。由于移动了 I2C 引脚，因此存在一些差异。 -
pins_rev2： Rev2 引脚设置。其中包括 P5 上的额外编解码器引脚。 -
pins_bplus1： Raspberry Pi 1 Model B+ rev 1.1，包括完整的 40 引脚连接器。 -
pins_bplus2： Raspberry Pi 1 Model B+ rev 1.2，交换了低功耗和 lan-run 引脚。 -
pins_aplus： Raspberry Pi 1 Model A+，缺少以太网。 -
pins_2b1： Raspberry Pi 2 Model B rev 1.0；通过 I2C0 控制 SMPS。 -
pins_2b2： Raspberry Pi 2 Model B rev 1.1；通过 42 和 43 上的软件 I2C 控制 SMPS。 -
pins_3b1： Raspberry Pi 3 Model B rev 1.0 -
pins_3b2： Raspberry Pi 3 Model B rev 1.2 -
pins_3bplus： Raspberry Pi 3 Model B+ -
pins_3aplus： Raspberry Pi 3 Model A+ -
pins_pi0： Raspberry Pi Zero -
pins_pi0w： Raspberry Pi Zero W -
pins_pi02w： Raspberry Pi Zero 2 W -
pins_cm： Raspberry Pi Compute Module 1。它的默认值是芯片的默认值，因此是有关芯片默认上拉/下拉的有用信息来源。 -
pins_cm3： Raspberry Pi Compute Module 3 -
pins_cm3plus： Raspberry Pi Compute Module 3+ -
pins_cm4s： Raspberry Pi Compute Module 4S -
pins_cm4： Raspberry Pi Compute Module 4
每个 pins_* 部分都可以包含 pin_config 和 pin_defines 部分。
pin_config
pin_config 部分用于配置各个引脚。此部分中的每个项目都必须是命名引脚部分，例如 pin@p32 ，即GPIO32。还有一个特殊部分 pin@default ，其中包含pin_config部分中未具体命名的任何内容的默认设置。
时钟配置
通过这个接口可以改变时钟的配置，不过很难预测结果！时钟系统的配置非常复杂。有五个独立的 PLL，每个 PLL 都有自己的固定（或可变，在 PLLC 的情况下）VCO 频率。然后，每个 VCO 都有若干不同的通道，可以对 VCO 频率进行不同的分频设置。每个时钟目的地都可以配置为来自其中一个时钟通道，不过源到目的地的映射是有限制的，因此并非所有通道都能路由到所有时钟目的地。
这里有几个配置示例，您可以用来更改特定时钟。如有时钟配置请求，我们将添加到此资源中。
clock_routing {
vco@PLLA { freq = <1966080000>; };
chan@APER { div = <4>; };
clock@GPCLK0 { pll = "PLLA"; chan = "APER"; };
};
clock_setup {
clock@PWM { freq = <2400000>; };
clock@GPCLK0 { freq = <12288000>; };
clock@GPCLK1 { freq = <25000000>; };
};上述操作将 PLLA 设置为运行于 1.96608GHz 的源 VCO（该 VCO 的限制频率为 600MHz - 2.4GHz），将 APER 通道更改为 /4，并将 GPCLK0 配置为通过 APER 从 PLLA 获取。这将为音频编解码器提供产生 48000 频率范围所需的 12288000Hz 频率。
示例设备树源文件
固件库包含一个 master Raspberry Pi blob，其他固件通常都是从它衍生出来的。