2. HAL 接口设计原则：稳定性、粒度与异步策略
做 HAL 接口设计，说白了就是在定规矩。规矩定得好，上层 Framework 用得顺手，底层硬件换了一茬又一茬，中间层也不用大改。我这些年踩过的坑，十有八九都跟接口设计脱不了干系。
今天咱们就掰开揉碎，聊聊 HAL 接口设计的四个核心维度：稳定性与兼容性、接口粒度、同步 vs 异步、回调机制。嗯，每个点我都会拿实际项目里的教训来说。
核心观点：HAL 接口是 Android 系统中“变化最频繁”与“最需要稳定”的矛盾体。上层希望接口不变，底层硬件每半年换一代。好的接口设计，就是在这两者之间找到平衡点。
2.1 接口稳定性与兼容性设计
先问一个问题：你改了一个 HAL 接口，Framework 层需要跟着改多少？
我见过最夸张的项目，一个 Camera HAL 接口从 v1.0 升到 v1.1，上层应用层改了 47 个文件。为什么？因为接口设计的时候根本没考虑向后兼容。
2.1.1 版本化接口
我个人习惯，每个 HAL 接口文件头部必须带版本号。不是写在注释里，而是用宏定义或者枚举写进代码里。
// hardware/libhardware/include/hardware/camera3.h
#define CAMERA_HARDWARE_MODULE_API_VERSION_3_5 HARDWARE_MODULE_API_VERSION(3, 5)
typedef struct camera_module {
hw_module_t common;
// v3.0 引入
int (*get_number_of_cameras)(void);
// v3.3 引入
int (*get_camera_info)(int camera_id, struct camera_info *info);
// v3.5 新增：热插拔回调注册
int (*set_camera_callbacks)(camera_module_callbacks_t *callbacks);
} camera_module_t;
你看，每个函数都有明确的引入版本。上层调用的时候，先查版本号，再决定能不能用这个函数。这就是最基本的兼容性保障。
我的经验：版本号不要用浮点数比较，容易出精度问题。用整数宏定义，比如 HARDWARE_MODULE_API_VERSION(3, 5) 展开成 0x0305，按位比较最稳。
2.1.2 接口扩展的“加新不加旧”原则
我曾经接手过一个项目，前任工程师为了“优化”，把原来的 open() 函数签名改了，多加了一个参数。结果所有老版本的 HAL 实现全部编译不过。这就是典型的反面教材。
正确的做法是：永远不要修改已有接口的签名。需要新功能？加新函数，加新结构体字段，加新版本号。
| 做法 | 后果 | 推荐 |
|---|---|---|
| 修改已有函数签名 | 老版本 HAL 全部编译失败 | ❌ 禁止 |
| 新增函数 + 版本判断 | 老版本 HAL 正常运行，新版本可选实现 | ✅ 推荐 |
| 结构体末尾追加字段 | 二进制兼容，老代码 sizeof 不匹配 | ⚠️ 需配合 size 字段校验 |
| 使用 padding 预留字段 | 未来扩展无需改结构体布局 | ✅ 推荐 |
注意：结构体扩展时，一定要在结构体头部加 uint32_t size; 字段。调用方传入 sizeof(your_struct)，实现方校验 size >= 所需最小版本。这是 Android HAL 的经典做法，也是我每次 code review 必查的点。
2.2 接口粒度的把控：粗粒度 vs 细粒度
接口粒度这个问题，你想想看，是不是经常遇到两种极端：
- 粗粒度：一个
doEverything()函数，传个 JSON 字符串进去，里面包了 20 个参数。上层调用简单，但底层解析复杂，而且没法复用。 - 细粒度：一个功能拆成 10 个函数，每个函数只做一件事。灵活是灵活了，但上层调一次功能要按顺序调 5 个函数，漏一个就崩。
我个人的判断标准很简单：看这个接口的调用频率和调用场景。
2.2.1 高频调用接口：细粒度
比如 Sensor HAL 的 poll() 函数，每秒调用几十上百次。这种接口必须细粒度，每次只返回最精简的数据。你要是把数据聚合、滤波、校准全塞进去，性能直接崩。
// 细粒度：每次只读一个 sensor 事件
int (*poll)(struct sensors_poll_device_t *dev,
sensors_event_t* data, int count);
// 粗粒度（反面）：一次返回所有 sensor 数据
int (*pollAll)(struct sensors_poll_device_t *dev,
char* json_output);
2.2.2 低频配置接口：粗粒度
像 Camera HAL 的 configure_streams()，一次配置管整个拍照流程。这种接口粗一点反而好，因为配置之间有依赖关系，拆太细容易出状态机混乱。
我的经验法则：
- 数据通路（data path）：细粒度，每次只传最小必要数据
- 控制通路（control path）：粗粒度，一次传完整配置
- 调试接口（debug）：无所谓，但别影响 release 性能
2.3 同步与异步接口的选择策略
同步还是异步？这个问题我当年纠结了整整两周。后来想明白一件事：看调用方能不能等。
2.3.1 同步接口：调用方可以阻塞等待
适合的场景：初始化、配置、查询状态。这些操作通常发生在启动阶段或者后台线程，调用方不介意等几十毫秒。
// 同步：初始化必须成功才能继续
int (*init)(struct hw_device_t* dev);
// 调用方：
if (device->init(dev) != 0) {
// 初始化失败，直接返回错误
return -ENODEV;
}
2.3.2 异步接口：调用方不能阻塞
适合的场景：数据流、长时间操作、UI 线程调用。比如 Camera 的 capture 请求，从发出到拿到图片可能要几百毫秒，UI 线程不可能等。
// 异步：发起请求，通过回调拿结果
int (*capture)(struct camera_device* dev,
camera_buffer_t* buffer,
camera_callback_t callback);
// 调用方：
device->capture(dev, buf, my_callback);
// 立即返回，不阻塞
避坑指南：我曾经在一个项目中把音频播放接口设计成同步的，结果上层 UI 一播放音乐就卡顿。后来改成异步 + 环形缓冲区，问题解决。记住：任何可能超过 5ms 的操作，都优先考虑异步。
2.4 回调机制的设计模式
回调是异步接口的“灵魂”。回调设计得好，代码像流水一样顺畅；设计得不好，那就是回调地狱。
2.4.1 注册式回调 vs 一次性回调
| 类型 | 特点 | 适用场景 |
|---|---|---|
| 注册式回调 | 一次注册，多次调用 | Sensor 数据上报、热插拔事件 |
| 一次性回调 | 每次请求带一个回调 | Camera capture、编码完成 |
我个人更倾向于一次性回调。为什么？因为注册式回调容易出生命周期问题——回调注册了，但调用方已经销毁了，回调触发时就是野指针。
2.4.2 回调的线程模型
回调在哪个线程执行？这是个必须明确的问题。我见过最坑的设计：回调文档里没写线程模型，结果上层在回调里加锁，底层也在加锁，直接死锁。
// 好的做法：在回调结构体里明确线程模型
typedef struct {
// 回调函数，在 HAL 的 worker 线程中调用
// 注意：不要在回调中执行耗时操作
void (*on_frame_ready)(void* user_data, frame_t* frame);
// 错误回调，在任意线程中调用
// 调用方需要自行处理线程切换
void (*on_error)(void* user_data, int error_code);
void* user_data; // 上下文指针
} camera_callbacks_t;
我曾经踩过的坑：有个项目，回调里直接调了 malloc()，而底层 HAL 刚好在信号处理函数里触发了回调。结果 malloc 不是信号安全的，直接死锁。从那以后，我要求所有回调文档必须写明：是否可重入、是否信号安全、是否允许阻塞。
2.5 本章知识结构图
下面这张图总结了 HAL 接口设计的四个核心维度，以及它们之间的关系。你可以把它当作设计时的检查清单。
2.6 小结
HAL 接口设计没有银弹。但如果你能把这四个维度想清楚——版本兼容、粒度匹配、同步异步选型、回调契约明确——至少能避免 80% 的集成问题。
嗯，这些原则说起来简单，真正落地的时候还是会有各种意外。我建议你每设计一个接口，都拿上面的检查清单过一遍。养成习惯后，你会发现 HAL 层的维护成本能降一半以上。