OpenBMC设备树配置手把手教程：适配新主板实践

OpenBMC设备树实战：从零开始适配一块新主板

你有没有遇到过这样的场景？
手头拿到一块全新的服务器主板，BMC芯片是Aspeed AST2500，原理图刚到手，团队等着你把OpenBMC跑起来。串口没输出、风扇不转、I2C设备扫描不到……问题接踵而至。

这时候你知道，真正的Bring-up战斗才刚刚开始。

而这场战斗的“第一道关卡”，就是——设备树（Device Tree）配置。

为什么是设备树？它到底在管什么？

别被名字唬住，“设备树”听起来高深，其实它的任务非常明确：告诉Linux内核“我们这块板子长什么样”。

比如：
- 哪些I2C总线是通的？
- 串口控制台连在UART1还是UART5？
- 温度传感器挂在哪个地址？
- 风扇PWM由哪个通道驱动？

这些问题的答案，统统写在.dts文件里。一旦写错，轻则外设失灵，重则系统卡死在启动初期。

💡关键点：OpenBMC不靠编译进内核的“板级代码”工作，而是靠外部加载的.dtb文件描述硬件。这意味着——改硬件不用重编内核，但必须改对设备树。

先搞清楚：Aspeed平台的设备树是怎么组织的？

大多数基于AST2400/2500/2600的BMC项目，设备树都遵循一套“分层继承”的结构：

ast2500.dtsi ← SoC级定义（寄存器、中断控制器、时钟） ↑ g4ddr3.dtsi ← 参考设计（典型内存配置、默认外设使能） ↑ my-xeon-bmc.dts ← 我们的自定义主板！在这里做裁剪和覆盖

这就像搭积木：底层是通用模块，上层只写差异部分。

举个实际例子：

// my-xeon-bmc.dts #include "ast2500.dtsi" #include "g4ddr3.dtsi" / { model = "MyCompany Dual-Xeon Server BMC"; compatible = "mycompany,xeon-bmc", "aspeed,ast2500"; memory@80000000 { reg = <0x80000000 0x20000000>; /* 512MB DDR3 */ }; chosen { stdout-path = "serial0:115200n8"; }; };

你看，我们并没有重复定义所有UART或I2C控制器，只是修改了几个关键节点：
-model：让系统知道自己是谁；
-memory：匹配实际颗粒大小；
-stdout-path：指定串口控制台路径，否则你看不到任何打印！

⚠️ 新手常踩的第一个坑：忘记设置stdout-path，结果串口黑屏，误以为U-Boot都没起来。

实战第一步：点亮串口控制台

没有日志，等于盲人摸象。所以第一步必须确保你能看到dmesg输出。

假设你的原理图显示：
- 串口控制台连接到 AST2500 的 UART1；
- 引脚复用为UART1_TXD/RXD；
- 波特率 115200。

那么你需要在设备树中启用并配置它：

&uart1 { status = "okay"; pinctrl-names = "default"; pinctrl-0 = <&pinctrl_uart1_default>; clock-frequency = <64000000>; /* AST2500 UART clock */ current-speed = <115200>; };

同时，在顶层添加引脚复用定义（如果参考设计未包含）：

&pinctrl { pinctrl_uart1_default: uart1-default { pins = "A17", "A18"; /* UART1_RXD, UART1_TXD */ function = "uart1"; }; };

编译烧录后，打开串口工具——终于看到熟悉的Starting kernel...了吗？恭喜，你已经跨过了最黑暗的一夜。

第二步：让I2C动起来——接上温度传感器LM75

现在来看一个典型的调试困境：

“我明明把LM75焊上去了，地址也对，i2cdetect -y 5却扫不到！”

先别急着查硬件。很可能只是设备树里忘了两件事：

✅ 1. 启用对应的I2C总线

默认情况下，很多I2C是status = "disabled"的。

找到.dtsi中的定义，比如：

i2c5: i2c@1e78a400 { status = "disabled"; // ... };

我们在自己的.dts文件中引用并启用它：

&i2c5 { status = "okay"; clock-frequency = <100000>; /* 100kHz standard mode */ lm75: temperature@48 { compatible = "national,lm75"; reg = <0x48>; }; };

就这么简单？没错。

只要compatible字符串正确，内核就会自动加载lm75驱动，并创建 hwmon 接口：

root@openbmc:~# ls /sys/class/hwmon/ hwmon0@ hwmon1@ root@openbmc:~# cat /sys/class/hwmon/hwmon1/temp1_input 25125 # 当前温度 25.125°C

🔍提示：如果你发现驱动没加载，检查dmesg | grep lm75是否报错。常见原因是compatible拼写错误，或者设备地址冲突。

GPIO与LED：不只是“亮灯”那么简单

面板上的电源灯、故障灯、UID指示灯，看似简单，实则最容易出逻辑反转的问题。

来看看正确的写法：

leds { compatible = "gpio-leds"; power_led: power { label = "Power LED"; gpios = <&gpio1 12 GPIO_ACTIVE_HIGH>; default-state = "on"; linux,default-trigger = "default-on"; }; fault_led { label = "Fault LED"; gpios = <&gpio7 4 GPIO_ACTIVE_LOW>; default-state = "off"; linux,default-trigger = "panic"; }; };

注意这里的细节：
-GPIO_ACTIVE_LOW表示低电平点亮，对应电路中的共阳极接法；
-linux,default-trigger = "panic"意味着系统崩溃时会自动闪烁；
- 用户可通过/sys/class/leds/fault/brightness手动控制。

🛠 调试技巧：运行时查看当前状态：

```bash
cat /sys/class/leds/power/brightness

输出 1 → 亮；0 → 灭

```

还有一个隐藏风险：引脚复用冲突。

同一个GPIO可能既可作普通IO，也可作PWM、ADC甚至按键输入。务必确认pinctrl设置正确，否则即使设备树写了GPIO，实际功能仍可能被锁定在其他模式。

PWM风扇控制：实现智能温控的核心

服务器不能一直全速转风扇，那样噪音大还费电。我们需要根据温度动态调节转速。

Aspeed 提供多达8路PWM输出。以PWM0为例：

&pwm_tach0 { status = "okay"; pwm_fan: pwm-fan@0 { compatible = "pwm-fan"; pwms = <&pwm0 0 5000000>; /* 周期5ms (200Hz) */ cooling-levels = <0 32 64 96 128 160 192 224 255>; num-trips = <2>; temp-trip-0 = <45000>; /* 45°C 进入中速 */ temp-trip-1 = <60000>; /* 60°C 进入高速 */ }; };

然后绑定到热区（thermal zone）：

thermal-zones { cpu_thermal: cpu-thermal { polling-delay = <5000>; trips { warn_trip: warning { temperature = <70000>; hysteresis = <5000>; type = "active"; }; }; cooling-maps { map0 { trip = <&warn_trip>; cooling-device = <&pwm_fan THERMAL_NO_LIMIT>; }; }; }; };

这样，当CPU温度超过70°C时，风扇将自动提升至最大档位。

🌡 验证方法：

bash watch -n 1 'cat /sys/class/hwmon/hwmon*/temp*_input' cat /sys/class/hwmon/hwmon*/pwm*

你会看到随着温度上升，pwm1的值逐渐增大。

Bring-up过程中最常遇到的三个“鬼故事”

❌ 问题1：I2C设备扫不到

排查清单：
- [ ] 总线是否已启用？status = "okay"
- [ ] 时钟频率是否过高？尝试降为<100000>
- [ ] 地址是否正确？对照原理图确认是0x48还是0x49
- [ ] 设备是否上电？用万用表测VCC
- [ ] 是否有上拉电阻？I2C无上拉必失败

工具推荐：

bash i2cdetect -l # 查看可用总线 i2cdetect -y 5 # 扫描I2C5 dmesg | grep i2c # 查看探测日志

❌ 问题2：LED不亮

灵魂三问：
1. 引脚编号写对了吗？gpio1 12是GP1_12吗？
2. 是高有效还是低有效？电路图上看清是PNP还是NPN驱动。
3. 引脚有没有被别的功能占用了？比如误设成了PWM输出。

💡 终极验证法：直接写GPIO调试接口

bash echo out > /sys/class/gpio/gpio12/direction echo 1 > /sys/class/gpio/gpio12/value

如果这时灯亮了，说明设备树配置有问题；如果不亮，查硬件。

❌ 问题3：系统启动卡住，串口无输出

这类问题往往发生在DDR或串口配置阶段。

重点检查项：
-memory@...的reg是否与实际容量一致？错一位就崩；
-stdout-path是否指向有效的串口？例如serial1对应的是哪个UART？
- 是否启用了错误的flash分区导致kernel加载失败？

🔬 建议使用JTAG+GDB进行早期调试，定位挂起位置。但对于多数开发者，串口仍是最快手段。

工程实践建议：如何写出可维护的设备树？

别想着一次写完就扔一边。好的设备树应该像代码一样易于迭代。

✅ 模块化拆分

将公共部分抽成.dtsi：

mycompany-common.dtsi ← 所有机型共用的GPIO、I2C命名等 ↑ xeon-server-bmc.dts ← 双路Xeon专用 arm-server-bmc.dts ← ARM架构专用

例如定义统一的LED命名规范：

// mycompany-common.dtsi #define POWER_LED_GPIO &gpio1 12 #define FAULT_LED_GPIO &gpio7 4

在具体板级文件中引用：

#include "mycompany-common.dtsi" leds { power_led { gpios = <POWER_LED_GPIO GPIO_ACTIVE_HIGH>; // ... }; };

未来换板只需改宏定义，无需遍历全文替换。

✅ 文档同步：建立“设备树-原理图”映射表

做一个表格，记录每个关键节点对应的原理图页码和功能说明：

这个表格将成为后续维护者的救命稻草。

✅ 安全默认值设计

某些关键GPIO在系统初始化期间必须处于安全状态，比如：

• POWRGD：电源良好信号，应保持高电平；
• RESET_RQ：远端复位请求，初始应为无效态；
• UID_SW：机箱UID开关，避免误触发。

可以在设备树中预设：

&gpio1 { power_good_pin: power-good { gpio-hog; output-high; line-name = "POWRGD"; gpios = <15>; }; };

gpio-hog表示该引脚由内核提前占用并初始化，防止驱动竞争。

写在最后：设备树不是终点，而是起点

当你成功让OpenBMC在新主板上稳定运行，串口输出清晰，I2C设备全部上线，风扇随温变化，LED按需闪烁……那一刻你会明白：

设备树，是你与硬件之间的第一份“契约”。

它不华丽，也不复杂，但它决定了整个系统的根基是否牢固。

掌握了设备树配置，你就不再是一个只会刷镜像的使用者，而是真正具备了底层Bring-up能力的嵌入式工程师。

接下来，你可以继续深入：
- 实现IPMI命令扩展；
- 开发Redfish REST API；
- 构建健康监控策略；
- 甚至参与上游社区贡献设备树补丁。

这条路很长，但每一步都算数。

如果你正在适配一块新板子，欢迎在评论区分享你的挑战和经验。也许下一次更新，我会加入你的案例。