📚 课程目录第4章传感器HAL接口规范

4、传感器HAL接口规范：理解 sensors.h 头文件、传感器模块结构体（sensors_module_t）、设备结构体（sensors_poll_device_t）、关键函数指针

Android传感器HAL（Hardware Abstraction Layer）是连接Android框架层（SensorService）与底层传感器芯片驱动的关键桥梁。无论是加速度计、陀螺仪、磁力计，还是光线、距离、温度传感器，最终都需要通过一套统一的C语言接口被上层系统识别和调用。这套接口的核心定义就位于 sensors.h 头文件中。本章将深入剖析该头文件的核心数据结构——sensors_module_t 与 sensors_poll_device_t，并逐一解读其关键函数指针的职责、调用时机与实现要点。理解这些规范，是编写一个能被系统正确加载、枚举并稳定采集数据的传感器HAL的前提。

上图清晰地展示了Android传感器HAL的整体架构关系。上层SensorService通过 hw_get_module() 获取HAL模块，再通过模块的 open() 方法打开设备，最终通过设备结构体中的函数指针完成数据交互。下面我们将逐一拆解这些关键定义。

4.1 sensors.h 头文件：HAL的“宪法”

sensors.h 位于Android源码的 hardware/libhardware/include/hardware/ 目录下，是所有传感器HAL实现必须包含的头文件。它定义了传感器类型常量、传感器列表结构、事件数据结构以及上述两个核心结构体。该头文件是Android硬件抽象层中少数几个“一次定义，多方使用”的公共接口，其稳定性直接影响系统兼容性。

核心原理上，sensors.h 通过宏定义和结构体声明，为上层提供了三个关键能力：传感器发现（通过 get_sensors_list）、传感器控制（通过 activate 和 setDelay）、数据读取（通过 poll）。任何传感器驱动，无论底层是I2C、SPI还是其他总线，都必须封装成这三个能力的实现。

头文件关键内容	说明	典型值/示例
传感器类型宏	定义各类传感器的整数ID	SENSOR_TYPE_ACCELEROMETER = 1
sensors_event_t	统一的事件数据结构	包含加速度、陀螺仪等联合体
sensors_module_t	模块入口，提供传感器列表	必须实现 get_sensors_list
sensors_poll_device_t	设备操作接口	包含 activate/setDelay/poll

实战提示：在编写HAL时，务必先包含 sensors.h，再包含 hardware.h。因为 sensors.h 内部已经引用了 hardware.h 中的基础结构体（如 hw_module_t），顺序错误会导致编译失败。

4.2 sensors_module_t：传感器列表的提供者

sensors_module_t 是HAL模块的“门面”，其定义如下：

typedef struct sensors_module_t {
    struct hw_module_t common;
    int (*get_sensors_list)(struct sensors_module_t* module,
                            struct sensor_t const** list);
} sensors_module_t;

该结构体在 hw_module_t 的基础上增加了一个函数指针 get_sensors_list。这个函数指针的作用是返回一个 sensor_t 数组，每个 sensor_t 描述一个传感器的静态属性（名称、厂商、类型、分辨率、最大范围、功耗等）。

判断方法：系统加载HAL时，会先通过 hw_get_module(SENSORS_HARDWARE_MODULE_ID, ...) 找到模块，然后调用 get_sensors_list 获取传感器列表。如果该函数返回的列表为空或指针为NULL，系统将认为没有传感器硬件，SensorService 会直接禁用所有传感器功能。

经验提醒：在实现 get_sensors_list 时，建议将传感器列表定义为 static 数组，避免动态内存分配。因为该函数可能在系统启动早期被调用，此时堆内存可能尚未完全初始化。同时，列表中的传感器ID（sensor_t.handle）必须唯一且稳定，后续所有操作（activate、poll）都依赖这个ID。

4.3 sensors_poll_device_t：数据交互的核心

sensors_poll_device_t 是HAL设备结构体，它继承自 hw_device_t，并定义了三个核心函数指针：

typedef struct sensors_poll_device_t {
    struct hw_device_t common;
    int (*activate)(struct sensors_poll_device_t *dev,
                    int handle, int enabled);
    int (*setDelay)(struct sensors_poll_device_t *dev,
                    int handle, int64_t ns);
    int (*poll)(struct sensors_poll_device_t *dev,
                sensors_event_t* data, int count);
} sensors_poll_device_t;

这三个函数构成了传感器数据流的完整生命周期：activate 控制传感器开关，setDelay 设置采样频率，poll 阻塞式获取数据。在Android 4.4（API 19）之后，还增加了 batch 函数指针用于批量模式，但基础三个函数是所有实现必须的。

操作流程：上层调用顺序通常为：先 activate(handle, 1) 使能传感器，再 setDelay(handle, 200000000) 设置200ms采样周期，然后循环调用 poll() 获取数据。当不再需要时，调用 activate(handle, 0) 关闭。

风险说明：poll() 函数是阻塞式的，如果传感器没有新数据，它必须一直等待。但要注意，如果 activate 被调用为禁用状态（enabled=0），poll() 必须立即返回，否则会导致上层线程永久挂起。建议在实现中使用条件变量或事件标志来处理这种状态切换。

4.4 关键函数指针的深度解析与实战案例

为了更直观地理解这些函数指针的协作方式，我们以一个虚拟的I2C接口加速度计（型号：ADXL345）为例，展示HAL实现的核心逻辑。

案例背景：某嵌入式设备使用ADXL345加速度计，通过I2C总线连接。系统要求HAL支持200ms和50ms两档采样率，且需要支持单次唤醒功能。初始现象是上层SensorService无法识别传感器，日志显示 get_sensors_list returned 0 sensors。

分析判断过程：通过查看日志，发现HAL模块加载成功，但 get_sensors_list 返回的列表长度为0。进一步检查代码，发现 sensor_t 数组定义在函数内部，函数返回后数组内存被释放，导致上层拿到野指针。这是典型的生命周期管理错误。

实际操作步骤：

将 sensor_t 数组改为 static 全局变量，确保生命周期与HAL模块一致。
在 get_sensors_list 中正确填充 sensor_t 的各个字段，包括 name、vendor、type、maxRange、resolution、power、minDelay 等。
实现 activate 函数，通过I2C寄存器操作ADXL345的Power Control寄存器（地址0x2D），写入0x08使能测量模式，写入0x00进入待机模式。
实现 setDelay 函数，根据传入的延迟值（ns）计算对应的输出数据速率（ODR），写入ADXL345的BW_RATE寄存器（地址0x2C）。例如，200ms对应5Hz，写入0x0A；50ms对应20Hz，写入0x0D。
实现 poll 函数，通过I2C读取DATAX0~DATAZ1六个寄存器（地址0x32~0x37），组合成16位有符号数，填充到 sensors_event_t 的 acceleration 联合体中。

结果对比：修复后，SensorService成功识别到加速度计，通过 getSensorList() 可以查询到传感器属性，registerListener() 后能稳定收到数据。功耗测试显示，在50ms采样率下，电流从待机的23µA上升到测量模式的145µA，符合ADXL345数据手册预期。

风险与代价：在实现 poll 时，如果I2C读取失败，需要返回错误码并重试，但不能无限阻塞。建议设置超时机制，例如使用 select() 或轮询方式，避免I2C总线故障导致系统卡死。

复盘经验：HAL开发中最常见的三类错误是：① 结构体生命周期管理不当（如局部变量返回）；② 函数指针未实现或返回错误码；③ 数据格式转换错误（如字节序、补码转换）。建议在开发初期就编写一个自测工具，直接调用HAL接口验证数据正确性，而不是依赖上层框架。

4.5 常见误区与总结复盘

在传感器HAL开发中，以下误区需要特别警惕：

误区一：忽略 sensor_t 的 minDelay 字段。该字段决定了传感器的最小采样周期（单位微秒），如果设置过大，上层无法实现高频采样；如果设置过小，底层硬件可能无法响应。
误区二：在 poll 中返回多个事件时未正确处理 count 参数。上层传入的 count 表示缓冲区可容纳的事件数，实现时必须确保返回的事件数不超过 count，否则会造成缓冲区溢出。
误区三：混淆 setDelay 的单位。该函数的参数 ns 是纳秒，而 sensor_t.minDelay 是微秒。转换时容易出错，建议统一使用纳秒进行内部计算。
误区四：未处理 activate 的重复调用。上层可能多次调用 activate(handle, 1)，实现需要具备幂等性，即重复使能不会导致硬件状态错乱。

总结：本章详细解析了 sensors.h 中两个核心结构体的定义与职责。sensors_module_t 负责提供传感器静态列表，sensors_poll_device_t 负责动态数据交互。理解这些接口的规范，是HAL开发的第一步。在实际项目中，建议先画出数据流图（参考本章SVG），明确每个函数指针的输入输出，再进行编码实现。下一阶段，我们将深入探讨 sensor_t 结构体的每个字段含义，以及如何为不同类型的传感器（加速度、陀螺仪、光线等）正确填充这些字段。