基于OpenBMC的ADC采集驱动开发实战案例

从零构建OpenBMC下的ADC采集系统：一个真实驱动开发全记录

在最近一次国产服务器平台的BMC开发任务中，我接手了一个看似简单却暗藏玄机的需求：通过OpenBMC实时监控主板上12路关键电源电压，并将数据接入Redfish API供远程调用。这听起来不就是读几个ADC通道吗？但真正动手才发现，背后涉及设备树配置、内核驱动适配、IIO子系统原理、精度校准甚至PCB走线干扰等一连串工程细节。

今天，我想把这段“踩坑—解题—优化”的完整过程分享出来，不仅告诉你代码怎么写，更讲清楚每一步背后的为什么。如果你正在做类似项目，希望这篇文章能让你少走几小时弯路。

问题起点：我们到底要解决什么？

先别急着敲代码。回到最原始的问题：

如何让一台远在机房的服务器，准确地告诉我它当前的3.3V、5V、12V供电是否正常？

传统做法可能是写个裸机程序轮询ADC寄存器，再通过串口打印。但在现代服务器管理场景下，我们需要的是：
-标准化接口：不同型号服务器换了个ADC芯片，软件不能重写；
-可扩展性：未来加个温度传感器不能推倒重来；
-远程访问能力：运维人员通过网页或API就能查看状态；
-高可靠性：哪怕主机宕机，BMC仍能上报异常。

正是这些需求催生了OpenBMC + Linux IIO的组合方案——它不是炫技，而是工业级系统的必然选择。

为什么选IIO？而不是直接操作寄存器？

你可能会问：“我自己用mmap映射ADC寄存器，每隔10ms读一次不行吗？”
技术上当然可以，但很快你会遇到这些问题：

每换一款SoC（比如从ASPEED换成STM32），寄存器地址和位定义全变了；
多个应用都想读ADC数据，谁负责加锁？
用户想查历史采样值怎么办？自己实现环形缓冲区？
怎么和其他服务（如风扇控制）共享数据？

而Linux的IIO（Industrial I/O）子系统正是为这类高精度、低速外设设计的标准框架。它的核心理念是：

一切传感器皆文件

这意味着一旦你的ADC驱动注册成功，系统会自动生成类似这样的路径：

/sys/bus/iio/devices/iio:device0/in_voltage0_raw

任何进程只要能读这个文件，就能拿到原始ADC码值。无需私有ioctl，无需特殊权限，也不依赖具体硬件型号。

更重要的是，IIO天然支持：
- 多通道管理
- 软件/硬件触发采集
- 缓冲区与事件机制
- scale/offset自动换算物理量

换句话说，IIO把你从繁琐的底层操作中解放出来，专注业务逻辑。

实战第一步：看懂我们的硬件环境

目标平台使用的是ASPEED AST2600SoC，内置一个8通道、12位分辨率的SAR型ADC模块。参考电压为3.3V，理论分辨率为：

$$
\frac{3.3V}{4096} \approx 0.805\,mV/LSB
$$

模拟信号来自主板上的分压网络，连接到ADC的AIN0~AIN7引脚。我们要采集的是：
- 12V主电源（经4:1分压后输入）
- 5V待机电压
- 多个3.3V域电压
- 温度传感器输出（NTC热敏电阻）

所有这些信息都必须通过设备树告诉内核：“这里有ADC，长这样，接在这里”。

设备树配置：给内核一张“硬件地图”

在OpenBMC中，设备树（Device Tree）是硬件与驱动之间的桥梁。没有它，即使驱动写得再完美，内核也不知道该在哪里找ADC控制器。

以下是我们在.dts文件中的关键片段：

&adc { status = "okay"; compatible = "aspeed,ast2600-adc"; reg = <0x1e6e2000 0x100>; interrupts = <GIC_SPI 68 IRQ_TYPE_LEVEL_HIGH>; clocks = <&syscon ASPEED_CLK_GATE_ADC>; vref-supply = <&vref_3v3>; /* 3.3V参考源 */ /* 定义各个输入通道 */ channel@0 { reg = <0>; label = "pwr_12v_rail"; type = "voltage"; differential = <0>; }; channel@1 { reg = <1>; label = "pwr_5v_standby"; type = "voltage"; }; channel@2 { reg = <2>; label = "temp_nct75_output"; type = "voltage"; }; };

几个关键点解释一下：

compatible字段决定了哪个驱动会被加载。如果匹配不到已有的IIO ADC驱动，我们就得自己写一个。
vref-supply明确指出参考电压来源，这对后续计算scale至关重要。
label是给人看的名字，在sysfs中也会体现，调试时非常有用。
reg中的数字对应ADC控制器内部的通道编号，不是GPIO。

修改完设备树后，需要用dtc编译成.dtb，并随固件一起烧录到BMC Flash中。

内核驱动实现：如何让ADC“活”起来

幸运的是，ASPEED系列已有上游支持的IIO驱动（drivers/iio/adc/aspeed_adc.c），我们不需要从零开始。但为了理解整个流程，不妨看看它是怎么工作的。

核心结构体：iio_dev 与 iio_chan_spec

每个IIO设备由一个struct iio_dev表示，其中最重要的两个成员是：

static const struct iio_chan_spec aspeed_adc_channels[] = { { .type = IIO_VOLTAGE, .channel = 0, .indexed = 1, .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE), }, // ... 其他通道 };

.type = IIO_VOLTAGE：表明这是一个电压输入通道；
.info_mask_separate：每个通道独有的属性，这里是RAW（原始值）；
.info_mask_shared_by_type：同类型通道共用的属性，如SCALE（量程系数）；

当用户读取/in_voltage0_raw时，内核就会调用驱动提供的read_raw回调函数。

数据读取：从寄存器到用户空间

static int aspeed_adc_read_raw(struct iio_dev *indio_dev, struct iio_chan_spec const *chan, int *val, int *val2, long mask) { struct aspeed_adc *adc = iio_priv(indio_dev); u32 reg_val; switch (mask) { case IIO_CHAN_INFO_RAW: mutex_lock(&adc->lock); regmap_write(adc->regmap, ASPEED_ADC_CTRL, ADC_EN | ADC_CH_SEL(chan->channel)); usleep_range(10, 20); /* 等待转换完成 */ regmap_read(adc->regmap, ASPEED_ADC_DATA, &reg_val); mutex_unlock(&adc->lock); *val = (reg_val >> 4) & 0xFFF; /* 提取12位结果 */ return IIO_VAL_INT; case IIO_CHAN_INFO_SCALE: *val = 3300; /* mV */ *val2 = 12; /* 12-bit -> 4096 steps */ return IIO_VAL_FRACTIONAL_LOG2; default: return -EINVAL; } }

这里有几个易错点需要注意：

加锁保护：ADC是共享资源，多线程并发访问必须互斥；
延时等待：SAR ADC需要建立时间，太快读取会导致数据错误；
位字段提取：AST2600的数据寄存器并非直接存放12位结果，需右移4位；
SCALE单位：返回的是微伏每LSB的对数形式，用户空间工具会自动处理。

驱动注册完成后，执行dmesg | grep iio应能看到：

iio iio:device0: aspeed-adc adc@1e6e2000: registered 8 channels

说明设备已就绪。

用户空间验证：用最简单的方式确认功能

接下来是最激动人心的时刻——第一次读取真实数据！

# 查看原始ADC码值 cat /sys/bus/iio/devices/iio:device0/in_voltage0_raw # 输出：3021 # 查看量程系数（单位 μV/LSB） cat /sys/bus/iio/devices/iio:device0/in_voltage_scale # 输出：805

计算实际电压：

real_voltage_uV=$((3021 * 805)) echo "Voltage: $((real_voltage_uV / 1000)) mV" # 输出：Voltage: 2431 mV → 即 2.431V

但这只是分压后的值！原始12V经过4:1分压，所以真实电压为：

$$
2.431V × 4 = 9.724V
$$

咦？偏低了？别急，这才引出下一个关键环节——校准。

精度优化：让数据真正可信

理想情况下，12V输入 → 分压后3V → ADC读数应为：

$$
\frac{3V}{3.3V} × 4096 ≈ 3724\,LSB
$$

但我们测出来只有3021，差了近700个码值。原因可能包括：

分压电阻公差（±1%很常见）；
参考电压实际为3.28V而非标称3.3V；
PCB走线引入压降；
ADC自身非线性误差（INL）。

解决办法是在设备树中加入校准参数：

&adc { // ... channel@0 { reg = <0>; label = "pwr_12v_rail"; type = "voltage"; bias = <0>; correction-scale = <0x10cc>; /* 4300 decimal → 相当于乘以1.048 */ correction-offset = <200>; /* 偏移补偿 */ }; };

然后在驱动中解析这些值，并动态调整scale：

if (of_property_read_u32(np, "correction-scale", &scale_x1000)) scale_x1000 = 1000; *val = 3300 * scale_x1000 / 1000; /* 应用修正系数 */

经过反复比对万用表实测值，最终我们将误差控制在±1%以内。这才是工业级产品应有的水准。

集成进OpenBMC生态：从数据到服务

现在ADC能准确读数了，但还不能被外部系统感知。我们需要让它进入OpenBMC的服务体系。

第一步：phosphor-hwmon 自动发现

OpenBMC提供了一个叫phosphor-hwmon的守护进程，它会周期性扫描/sys/class/hwmon/和/sys/bus/iio/下的设备，并将符合命名规则的传感器通过D-Bus发布出去。

为了让IIO设备被识别，我们可以创建一个udev规则：

# /etc/udev/rules.d/99-iio-sensor.rules KERNEL=="iio:device*", SUBSYSTEM=="iio", \ ATTR{name}=="aspeed-adc", \ SYMLINK+="hwmon/iio_hwmon"

同时确保设备名为aspeed-adc，这样phosphor-hwmon就会自动将其映射为 D-Bus 对象：

xyz.openbmc_project.Sensor.Value:/xyz/openbmc_project/sensors/voltage/pwr_12v_rail

第二步：通过Redfish查看数据

重启服务后，即可通过REST API查询：

curl -k https://<bmc-ip>/redfish/v1/Chassis/1/Sensors/Voltage/ \ -H "X-Auth-Token: $token"

响应中会出现：

{ "Name": "pwr_12v_rail", "ReadingVolts": 11.87, "UpperThresholdCritical": 13.2, "LowerThresholdCritical": 10.8 }

至此，一条完整的“模拟信号→数字值→系统服务→远程接口”链路彻底打通。

常见坑点与调试秘籍

在这次开发中，我们踩过不少坑，总结出以下几点经验：

❌ 问题1：读数跳动大，噪声严重

现象：同一电压多次读取波动超过±50mV。
排查：用示波器检查ADC输入引脚，发现存在高频振铃。
解决：
- 在ADC输入端增加RC低通滤波（10kΩ + 10nF）；
- 模拟电源增加去耦电容（0.1μF陶瓷 + 10μF钽电容）；
- 避免模拟走线与PWM风扇控制线平行走线。

❌ 问题2：某些通道始终返回0

现象：AIN3读数恒为0，其他正常。
排查：检查设备树发现reg = <4>写成了<3>，导致通道错位。
教训：务必核对SoC手册中的通道映射表，不要凭直觉猜测。

❌ 问题3：scale显示为0或负数

现象：in_voltage_scale返回-2147483648这种诡异值。
原因：read_raw函数未正确处理IIO_VAL_FRACTIONAL_LOG2类型，返回顺序错了。
修复：确认return IIO_VAL_FRACTIONAL_LOG2时，*val是分子，*val2是分母的log2。

✅ 调试利器推荐

iiod+iio_info工具（来自 libiio）：
bash iio_info -s localhost
可远程查看所有IIO设备及其属性。
启用内核debug输出：
c dev_dbg(dev, "ADC raw: 0x%x, channel: %d\n", reg_val, chan->channel);
使用configfs动态配置缓冲区进行高速采样（适用于纹波分析）。