1. 简介

2. 驱动

大部分传感器都会使用iio驱动框架，以light sensor为例

3. sensor hal

3.1 sensor hal 2.0接口

sensor hal 2.0的几个接口说明，参考ISensors.hal

getSensorsList()

getSensorsList() generates (vec<SensorInfo> list);

getSensorsList()函数用于获取当前设备的所有可用的sensors，返回值为SensorInfo，该结构体定义如下，

struct SensorInfo {
    /**
     * handle that identifies this sensors. This handle is used to reference
     * this sensor throughout the HAL API.
     */
    int32_t sensorHandle;

    /**
     * Name of this sensor.
     * All sensors of the same "type" must have a different "name".
     */
    string name;

    /** vendor of the hardware part */
    string vendor;

    /**
     * version of the hardware part + driver. The value of this field
     * must increase when the driver is updated in a way that changes the
     * output of this sensor. This is important for fused sensors when the
     * fusion algorithm is updated.
     */
    int32_t version;

    /** this sensor's type. */
    SensorType type;

    /**
     * type of this sensor as a string.
     *
     * When defining an OEM specific sensor or sensor manufacturer specific
     * sensor, use your reserve domain name as a prefix.
     * e.g. com.google.glass.onheaddetector
     *
     * For sensors of known type defined in SensorType (value <
     * SensorType::DEVICE_PRIVATE_BASE), this can be an empty string.
     */
    string typeAsString;

    /** maximum range of this sensor's value in SI units */
    float maxRange;

    /** smallest difference between two values reported by this sensor */
    float resolution;

    /** rough estimate of this sensor's power consumption in mA */
    float power;

    /**
     * this value depends on the reporting mode:
     *
     *   continuous: minimum sample period allowed in microseconds
     *   on-change : 0
     *   one-shot  :-1
     *   special   : 0, unless otherwise noted
     */
    int32_t minDelay;

    /**
     * number of events reserved for this sensor in the batch mode FIFO.
     * If there is a dedicated FIFO for this sensor, then this is the
     * size of this FIFO. If the FIFO is shared with other sensors,
     * this is the size reserved for that sensor and it can be zero.
     */
    uint32_t fifoReservedEventCount;

    /**
     * maximum number of events of this sensor that could be batched.
     * This is especially relevant when the FIFO is shared between
     * several sensors; this value is then set to the size of that FIFO.
     */
    uint32_t fifoMaxEventCount;

    /**
     * permission required to see this sensor, register to it and receive data.
     * Set to "" if no permission is required. Some sensor types like the
     * heart rate monitor have a mandatory require_permission.
     * For sensors that always require a specific permission, like the heart
     * rate monitor, the android framework might overwrite this string
     * automatically.
     */
    string requiredPermission;

    /**
     * This value is defined only for continuous mode and on-change sensors.
     * It is the delay between two sensor events corresponding to the lowest
     * frequency that this sensor supports. When lower frequencies are requested
     * through batch()/setDelay() the events will be generated at this frequency
     * instead.
     * It can be used by the framework or applications to estimate when the
     * batch FIFO may be full.
     *
     * NOTE: periodNs is in nanoseconds where as maxDelay/minDelay are in
     *       microseconds.
     *
     *       continuous, on-change: maximum sampling period allowed in
     *                              microseconds.
     *
     *          one-shot, special : 0
     */
    int32_t maxDelay;

    /** Bitmask of SensorFlagBits */
    bitfield<SensorFlagBits> flags;
};

setOperationMode()

setOperationMode设置模块的模式，有两种选择，SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module.SENSOR_HAL_DATA_INJECTION_MODE - Loopback mode.Data is injected for the supported sensors by the sensor service in this mode.

setOperationMode(OperationMode mode) generates (Result result);

activate()

activate()用来activate/de-activate一个sensor，在de-activate一个sensor后，尚未写入事件队列的现有传感器事件必须立即丢弃，以便后续的激活不会得到陈旧的传感器事件（即在后续激活之前生成的事件）。
enabled设置为true激活一个传感器，设置为false停用一个传感器。

activate(int32_t sensorHandle, bool enabled) generates (Result result);

initialize()

initialize()函数用于初始化hal的快速消息队列Fast Message Queues (FMQ)和回调函数。快速消息队列（FMQ）用于在框架和HAL之间发送数据。回调由HAL用于通知框架异步事件，例如动态传感器的连接。
事件FMQ用于将传感器事件从HAL传输到框架。使用 eventQueueDescriptor 创建事件FMQ。只能将数据写入事件FMQ，不得从事件FMQ读取数据，因为框架是唯一的读取者。收到传感器事件后，HAL将传感器事件写入事件FMQ。

一旦HAL完成将传感器事件写入事件FMQ，HAL必须通知框架可以读取和处理传感器事件。有两种方式实现：

调用事件FMQ的 EventFlag::wake() 函数，使用 EventQueueFlagBits::READ_AND_PROCESS
在事件FMQ的 writeBlocking() 函数中将写通知设置为 EventQueueFlagBits::READ_AND_PROCESS。

// Initialize the Sensors HAL's Fast Message Queues (FMQ) and callback.
// @param eventQueueDescriptor Fast Message Queue descriptor that is used to
//           create the Event FMQ which is where sensor events are written. The
//           descriptor is obtained from the framework's FMQ that is used to read
//           sensor events.
// @param wakeLockDescriptor Fast Message Queue descriptor that is used to
//           create the Wake Lock FMQ which is where wake_lock events are read
//           from. The descriptor is obtained from the framework's FMQ that is
//           used to write wake_lock events.
// @param sensorsCallback sensors callback that receives asynchronous data
//           from the Sensors HAL.
//           @return result OK on success; BAD_VALUE if descriptor is invalid (such
//           as null)
    @entry
    @callflow(next = {"getSensorsList"})
    initialize(fmq_sync<Event> eventQueueDescriptor,
               fmq_sync<uint32_t> wakeLockDescriptor,
               ISensorsCallback sensorsCallback)
        generates
              (Result result);

batch()

设置传感器的参数，包括采样频率和最大报告延迟。此函数可在传感器处于激活状态时调用，此时不能导致任何传感器测量数据的丢失：从一个采样率过渡到另一个采样率不能导致事件丢失，也不能从高最大报告延迟过渡到低最大报告延迟导致事件丢失。

/*
@param sensorHandle 要更改的传感器句柄。
@param samplingPeriodNs 指定传感器样本周期，以纳秒为单位。
@param maxReportLatencyNs 在事件被采样到报告时间之前允许的延迟时间。
@return 成功时返回 OK，如果任何参数无效则返回 BAD_VALUE。
*/
    batch(int32_t sensorHandle,
          int64_t samplingPeriodNs,
          int64_t maxReportLatencyNs)
        generates (
          Result result);

flush()

刷新将向指定传感器的“批处理模式”FIFO末尾添加一个 FLUSH_COMPLETE 元数据事件，并刷新FIFO。如果FIFO为空或传感器不支持批处理（FIFO大小为零），则返回 SUCCESS，并在事件流中添加一个简单的 FLUSH_COMPLETE 事件。这适用于除单次触发传感器之外的所有传感器。如果传感器是单次触发传感器，刷新必须返回 BAD_VALUE，并且不生成任何刷新完成的元数据。如果在调用 flush() 时传感器处于非活动状态，flush() 必须返回 BAD_VALUE。

// Trigger a flush of internal FIFO.
flush(int32_t sensorHandle) generates (Result result);

injectSensorData()

当设备处于 NORMAL 模式时，调用此函数将操作环境数据推送到设备。在此操作中，事件始终为 SensorType::AdditionalInfo 类型。
当设备处于 DATA_INJECTION 模式时，此函数还用于注入传感器事件。
无论 OperationMode 如何，注入的 SensorType::ADDITIONAL_INFO 类型事件不应路由回传感器事件队列。

// Inject a single sensor event or push operation environment parameters to device.
injectSensorData(Event event) generates (Result result);

registerDirectChannel()
使用提供的共享内存信息注册直接通道。在返回时，传感器硬件负责将内存内容重置为初始值（取决于内存格式设置）。

// Register direct report channel.
registerDirectChannel(SharedMemInfo mem)
               generates (Result result,
                          int32_t channelHandle);

SharedMemInfo结构体定义如下，


/**
 * Shared memory information for a direct channel
 */
struct SharedMemInfo {
    SharedMemType type;         // shared memory type
    SharedMemFormat format;
    uint32_t size;              // size of the memory region, in bytes
    handle memoryHandle;        // shared memory handle, it is interpreted
                                // depending on type field, see SharedMemType.
};

/**
 * Direct channel shared memory types. See struct SharedMemInfo.
 */
@export(name="direct_mem_type_t", value_prefix="SENSOR_DIRECT_MEM_TYPE_")
enum SharedMemType : int32_t {
    // handle contains 1 fd (ashmem handle) and 0 int.
    ASHMEM = 1,
    // handle definition matches gralloc HAL.
    GRALLOC
};

/**
 * Direct channel lock-free queue format, this defines how the shared memory is
 * interpreted by both sensor hardware and application.
 *
 * @see SharedMemInfo.
 */
@export(name="direct_format_t", value_prefix="SENSOR_DIRECT_FMT_")
enum SharedMemFormat : int32_t {
    SENSORS_EVENT = 1,  // shared memory is formated as an array of data
                        // elements. See SensorsEventFormatOffset for details.
                        // Upon return of channel registration call, the
                        // shared memory space must be formated to all 0 by HAL.
};

unregisterDirectChannel()
注销先前使用 registerDirectChannel 注册的直接通道，并移除在该直接通道中配置的所有活动传感器报告。
```
// Unregister direct report channel.
unregisterDirectChannel(int32_t channelHandle) generates (Result result);
```
configDirectReport()

此函数启动、修改速率或停止在特定直接通道中传感器的直接报告。

// Configure direct sensor event report in direct channel.
    configDirectReport(
            int32_t sensorHandle,
            int32_t channelHandle,
            RateLevel rate
        ) generates (
            Result result,
            int32_t reportToken);
            

/**
 * Direct report rate level definition. Except for SENSOR_DIRECT_RATE_STOP, each
 * rate level covers the range (55%, 220%] * nominal report rate. For example,
 * if config direct report specify a rate level SENSOR_DIRECT_RATE_FAST, it is
 * legal for sensor hardware to report event at a rate greater than 110Hz, and
 * less or equal to 440Hz. Note that rate has to remain steady without variation
 * before new rate level is configured, i.e. if a sensor is configured to
 * SENSOR_DIRECT_RATE_FAST and starts to report event at 256Hz, it cannot
 * change rate to 128Hz after a few seconds of running even if 128Hz is also in
 * the legal range of SENSOR_DIRECT_RATE_FAST. Thus, it is recommended to
 * associate report rate with RateLvel statically for single sensor.
 */
@export(name="direct_rate_level_t", value_prefix="SENSOR_DIRECT_RATE_")
enum RateLevel : int32_t {
    STOP,            // stop
    NORMAL,          // nominal 50Hz
    FAST,            // nominal 200Hz
    VERY_FAST,       // nominal 800Hz
};

3.2 具体hal实现

可参考Android12源码中两个google的实现：
device/generic/goldfish/sensors/
device/google/trout/hal/sensors/2.0

Android sensor hal框架