芯片厂商开放
YunOS Hardware Abstract Layer -- Sensor
文档内容拷贝自：
codebase_host/yunhal/opendoc/zh/yunhal_doc/sensors.md
联系人：@黄啸
1. 概述(Introduction)
本文档介绍了YunOS Sensor Framework的整体软件框架设计，并详细介绍了YunOS Sensor Hardware Abstract Layer，后文称Sensor Yunhal，为芯片厂商如何进行实现工作提供了指导。此外，本文档提供了对Sensor YunHal接口基本功能的测试程序及其使用方法，以便厂商快速调试Sensor基本功能是否OK。
2. 架构(Sensor Framework Architecture)
YunOS Sensor Framework整体软件架构如图2.1所示：
Client端为APP提供C++和JavaScript两套Sensor API；Server端则是一个后台服务Daemon，通过Socket来处理Client端命令并最终转换成Sensor YunHal接口，同时也将Hal产生的数据分发到各个Sensor Client。
3. 实现(Implement Sensor HAL)
芯片厂商需要针对自身Sensor hardware的能力提供YunHal的实现，函数接口定义在yunhal/Sensor.h头文件中，下面将具体介绍。
3.1 接口定义
Sensor YunHal分别通过 sens_module_t 和 sens_op_t 来描述Hal模块和具体执行的接口，同时，为了能够使用YunHal提供的统一接口，
sens_module_t 和 sens_op_t 分别”继承“了 VendorModule 和 VendorDevice 。Sensor YunHal的实现即具体来实现上述接口，可以分成两步：
1. 实现 sens_module_t 接口, 声明模块入口；
2. 实现 sens_op_t 接口；
3.1.1 实现 sens_module_t 接口
sens_module_t 各字段说明如下表：
| 域 | 类型 | 说明 |
|---|---|---|
| common | VendorModule | 模块入口 |
| reserved | function | 保留字段，扩展使用 |
声明模块入口，是为了Sensor YunHal的实现模块，能被libhal所装载，示例代码如下：
sens_module_t sens_module = {
.common = {
.version = SENSOR_YUNHAL_API_VERSION_0_0,
.id = "sensor",
.name = "YunOS Sensor Module",
.author = "YunOS",
.CreateDevice = create_device,
},
.reserved = {NULL},
};
VENDOR_MODULE_ENTRY(sens_module)
其中，version字段描述Sensor YunHal接口的版本，会随着接口的演进来更新，目前为 SENSOR_YUNHAL_API_VERSION_0_0 ；CreateDevice则是一个工厂方法，用来生产 sens_op_t 。
3.1.2 实现 sens_op_t 接口
| 域 | 类型 | 说明 |
|---|---|---|
| __common__ | VendorDevice | 设备入口 |
| __init()__ | void *(* init)() | Sensor操作初始化函数 |
| __exit()__ | void (* exit)() | Sensor操作结束函数 |
| __get_all_sensors()__ | int (* get_all_sensors)(void *ctx, sens_info_t const** list) | 获取全部Sensor设备 |
| __enable()__ | int (* enable)(void *ctx, int id, int enabled) | 打开关闭Sensor |
| __config()__ | int (* config)(void *ctx, int id, int64_t period_ns, int64_t max_latency_ns, int options) | 设置batch参数 |
| __flush()__ | int (* flush)(void *ctx, int id) | 刷新Sensor FIFO |
| __poll_event()__ | int (* poll_event)(void *ctx, sens_event_t* data, int max_num) | 获取Sensor数据 |
| __resvd__ | void * | 保留字段，扩展使用 |
示例代码如下：
sens_op_t sens_op = {
.common = {
.version = SENSOR_YUNHAL_API_VERSION_0_0,
.id = NULL,
.module = NULL,
.Destroy = NULL,
},
.init = init,
.exit = exit,
.get_all_sensors = get_all_sensors,
.enable = enable,
.config = config,
.flush = flush,
.poll_event = poll_event,
.resvd = {NULL},
};
3.2 编译
Sensor HAL 实现中，确保对 YunOS 主镜像具有最小的依赖，即除了 glibc、libstdc++ 以及 liblog 以外，不依赖其他 libraries。
一个示例的 yunos.mk 如下：
LOCAL_PATH=$(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := my_sensor
LOCAL_MODULE_PATH := usr/lib/yunhal
LOCAL_SRC_FILES := my_sensor.c
LOCAL_C_INCLUDES := \
$(yunhal-includes) \
$(base-includes)
LOCAL_SHARED_LIBRARIES := libhal liblog
LOCAL_COMPILE_SHELL_CMD := \
mkdir -p $(XMAKE_ROOTFS)/usr/lib/yunhal/ && \
ln -sf my_sensor.so $(XMAKE_ROOTFS)/usr/lib/yunhal/libyunhal_Sensor.so
# May be changed to include $(BUILD_HAL) ?
include $(BUILD_SHARED_LIBRARY)
4. 测试(Vendor Test Suite)
4.1 介绍
Sensor Yunhal Gtest是基于gtest开发的，通过Sensor.h定义的Sensor Yunhal APIs，对vendor实现的Yunhal进行自动化测试；也可以通过Yunhal对Android Hal的Wrapper，对vendor提供的Android Hal进行测试。本Test测试了Yunhal定义的全部API，并验证获取数据的合法性，以最小的effect测试厂商实现的Yunhal，便于厂商快速进行Sensor Framework 适配。
4.2 测试用例
| 模块 | 测试用例 | 说明 | 备注 |
|---|---|---|---|
| Sensor Yunhal | SensorYunHalTest | 1. 测试Sensor Yunhal加载是否正常。 2.测试Sensor Yunhal相关数据结构设置是否正确。 3. 依次调用Sensor Yunhal API。 4. 验证Yunhal上报数据。 |
N/A |
4.3 使用说明
执行: yunhal_tests –gtest_filter=SensorYunHalTest.*
成功的情况:
poll_event无数据导致失败的情况（9832N会遇到）:
