Android HAl 学习笔记

硬件抽象层 (HAL)

        HAL 可定义一个标准接口以供硬件供应商实现，这可让 Android 忽略较低级别的驱动程序实现。借助 HAL，您可以顺利实现相关功能，而不会影响或更改更高级别的系统。HAL 实现会被封装成模块，并由 Android 系统适时地加载。供应商为产品所提供的特定硬件实现相应的 HAL（和驱动程序）。HAL 实现通常会内置在共享库模块（.so 文件）中。每个特定于硬件的 HAL 接口都要具有 hardware/libhardware/include/hardware/hardware.h 中定义的属性。这类接口可让 Android 系统以一致的方式加载 HAL 模块的正确版本。HAL 接口包含两个组件：模块和设备。

/**
 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 * and the fields of this data structure must begin with hw_module_t
 * followed by module specific information.
 */
typedef struct hw_module_t {
    /** tag must be initialized to HARDWARE_MODULE_TAG */
    uint32_t tag;

    /**
     * The API version of the implemented module. The module owner is
     * responsible for updating the version when a module interface has
     * changed.
     *
     * The derived modules such as gralloc and audio own and manage this field.
     * The module user must interpret the version field to decide whether or
     * not to inter-operate with the supplied module implementation.
     * For example, SurfaceFlinger is responsible for making sure that
     * it knows how to manage different versions of the gralloc-module API,
     * and AudioFlinger must know how to do the same for audio-module API.
     *
     * The module API version should include a major and a minor component.
     * For example, version 1.0 could be represented as 0x0100. This format
     * implies that versions 0x0100-0x01ff are all API-compatible.
     *
     * In the future, libhardware will expose a hw_get_module_version()
     * (or equivalent) function that will take minimum/maximum supported
     * versions as arguments and would be able to reject modules with
     * versions outside of the supplied range.
     */
    uint16_t module_api_version;
#define version_major module_api_version
    /**
     * version_major/version_minor defines are supplied here for temporary
     * source code compatibility. They will be removed in the next version.
     * ALL clients must convert to the new version format.
     */

    /**
     * The API version of the HAL module interface. This is meant to
     * version the hw_module_t, hw_module_methods_t, and hw_device_t
     * structures and definitions.
     *
     * The HAL interface owns this field. Module users/implementations
     * must NOT rely on this value for version information.
     *
     * Presently, 0 is the only valid value.
     */
    uint16_t hal_api_version;
#define version_minor hal_api_version

    /** Identifier of module */
    const char *id;

    /** Name of this module */
    const char *name;

    /** Author/owner/implementor of the module */
    const char *author;

    /** Modules methods */
    struct hw_module_methods_t* methods;

    /** module's dso */
    void* dso;

#ifdef __LP64__
    uint64_t reserved[32-7];
#else
    /** padding to 128 bytes, reserved for future use */
    uint32_t reserved[32-7];
#endif

} hw_module_t;

typedef struct hw_module_methods_t {
    /** Open a specific device */
    int (*open)(const struct hw_module_t* module, const char* id,
            struct hw_device_t** device);

} hw_module_methods_t;

/**
 * Every device data structure must begin with hw_device_t
 * followed by module specific public methods and attributes.
 */
typedef struct hw_device_t {
    /** tag must be initialized to HARDWARE_DEVICE_TAG */
    uint32_t tag;

    /**
     * Version of the module-specific device API. This value is used by
     * the derived-module user to manage different device implementations.
     *
     * The module user is responsible for checking the module_api_version
     * and device version fields to ensure that the user is capable of
     * communicating with the specific module implementation.
     *
     * One module can support multiple devices with different versions. This
     * can be useful when a device interface changes in an incompatible way
     * but it is still necessary to support older implementations at the same
     * time. One such example is the Camera 2.0 API.
     *
     * This field is interpreted by the module user and is ignored by the
     * HAL interface itself.
     */
    uint32_t version;

    /** reference to the module this device belongs to */
    struct hw_module_t* module;

    /** padding reserved for future use */
#ifdef __LP64__
    uint64_t reserved[12];
#else
    uint32_t reserved[12];
#endif

    /** Close this device */
    int (*close)(struct hw_device_t* device);

} hw_device_t;

**
 * Get the module info associated with a module by id.
 *
 * @return: 0 == success, <0 == error and *module == NULL
 */
int hw_get_module(const char *id, const struct hw_module_t **module);

/**
 * Get the module info associated with a module instance by class 'class_id'
 * and instance 'inst'.
 *
 * Some modules types necessitate multiple instances. For example audio supports
 * multiple concurrent interfaces and thus 'audio' is the module class
 * and 'primary' or 'a2dp' are module interfaces. This implies that the files
 * providing these modules would be named audio.primary.<variant>.so and
 * audio.a2dp.<variant>.so
 *
 * @return: 0 == success, <0 == error and *module == NULL
 */
int hw_get_module_by_class(const char *class_id, const char *inst,
                           const struct hw_module_t **module);

HAL 模块

模块表示被封装且存储为共享库 (.so file) 的 HAL 实现。hardware/libhardware/include/hardware/hardware.h 标头文件会定义一个表示模块的结构体 (hw_module_t)，其中包含模块的版本、名称和作者等元数据。Android 会根据这些元数据来找到并正确加载 HAL 模块。

另外，hw_module_t 结构体还包含指向另一个结构体 hw_module_methods_t 的指针，后面这个结构体会包含一个指向相应模块的 open 函数的指针。此 open 函数用于与相关硬件（此 HAL 是其抽象形式）建立通信。每个特定于硬件的 HAL 通常都会使用附加信息为该特定硬件扩展通用的 hw_module_t结构体。例如，在相机 HAL 中，camera_module_t 结构体会包含一个 hw_module_t 结构体以及其他特定于相机的函数指针：

typedef struct camera_module {
    hw_module_t common;
    int (*get_number_of_cameras)(void);
    int (*get_camera_info)(int camera_id, struct camera_info *info);
} camera_module_t;

实现 HAL 并创建模块结构体时，您必须将其命名为 HAL_MODULE_INFO_SYM。以下是 Nexus 9 音频 HAL 的示例：

struct audio_module HAL_MODULE_INFO_SYM = {
    .common = {
        .tag = HARDWARE_MODULE_TAG,
        .module_api_version = AUDIO_MODULE_API_VERSION_0_1,
        .hal_api_version = HARDWARE_HAL_API_VERSION,
        .id = AUDIO_HARDWARE_MODULE_ID,
        .name = "NVIDIA Tegra Audio HAL",
        .author = "The Android Open Source Project",
        .methods = &hal_module_methods,
    },
};

HAl 设备

设备是产品硬件的抽象表示。例如，一个音频模块可能包含主音频设备、USB 音频设备或蓝牙 A2DP 音频设备。

设备由 hw_device_t 结构体表示。与模块类似，每类设备都定义了一个通用 hw_device_t 的详细版本，其中包含指向硬件特定功能的函数指针。例如，audio_hw_device_t 结构体类型会包含指向音频设备操作的函数指针：

struct audio_hw_device {
    struct hw_device_t common;

    /**
     * used by audio flinger to enumerate what devices are supported by
     * each audio_hw_device implementation.
     *
     * Return value is a bitmask of 1 or more values of audio_devices_t
     */
    uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
  ...
};
typedef struct audio_hw_device audio_hw_device_t;

camera hal module:

camera_common.h 可定义 camera_module；这是一个标准结构，可用于获取有关相机的一般信息，例如相机 ID 和所有相机通用的属性（例如，摄像头是前置摄像头还是后置摄像头）。

typedef struct camera_info {
    int facing;
    int orientation;
    uint32_t device_version;
    const camera_metadata_t *static_camera_characteristics;
    int resource_cost;
    char** conflicting_devices;
    size_t conflicting_devices_length;
} camera_info_t;

/**
 * camera_device_status_t:
 *
 * The current status of the camera device, as provided by the HAL through the
 * camera_module_callbacks.camera_device_status_change() call.
 */
typedef enum camera_device_status {
    CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
    CAMERA_DEVICE_STATUS_PRESENT = 1,
    CAMERA_DEVICE_STATUS_ENUMERATING = 2,
} camera_device_status_t;

typedef enum torch_mode_status {
    TORCH_MODE_STATUS_NOT_AVAILABLE = 0,
    TORCH_MODE_STATUS_AVAILABLE_OFF = 1,
    TORCH_MODE_STATUS_AVAILABLE_ON = 2,
} torch_mode_status_t;

typedef struct camera_module_callbacks {
    void (*camera_device_status_change)(const struct camera_module_callbacks*,
            int camera_id,
            int new_status);
    void (*torch_mode_status_change)(const struct camera_module_callbacks*,
            const char* camera_id,
            int new_status);
} camera_module_callbacks_t;

typedef struct camera_module {
    hw_module_t common;
    int (*get_number_of_cameras)(void);
    int (*get_camera_info)(int camera_id, struct camera_info *info);
    int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
    void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
    int (*open_legacy)(const struct hw_module_t* module, const char* id,
            uint32_t halVersion, struct hw_device_t** device);
    int (*set_torch_mode)(const char* camera_id, bool enabled);
    int (*init)();
    /* reserved for future use */
    void* reserved[5];
} camera_module_t;

camera hal device

camera.h 包含对应于 android.hardware.Camera 的代码。此标头文件会声明一个 camera_device 结构，该结构又反过来包含一个带函数指针（可实现 HAL 接口）的 camera_device_ops 结构。有关开发者可以设置的相机参数的文档，请参阅 frameworks/av/include/camera/CameraParameters.h。通过 HAL 中的 int (*set_parameters)(struct camera_device *, const char *parms) 来设置这些参数以及指向的函数

typedef enum camera3_stream_type {
    CAMERA3_STREAM_OUTPUT = 0,
    CAMERA3_STREAM_INPUT = 1,
    CAMERA3_STREAM_BIDIRECTIONAL = 2,
    /**
     * Total number of framework-defined stream types
     */
    CAMERA3_NUM_STREAM_TYPES
} camera3_stream_type_t;

typedef enum camera3_stream_rotation {
    /* No rotation */
    CAMERA3_STREAM_ROTATION_0 = 0,

    /* Rotate by 90 degree counterclockwise */
    CAMERA3_STREAM_ROTATION_90 = 1,

    /* Rotate by 180 degree counterclockwise */
    CAMERA3_STREAM_ROTATION_180 = 2,

    /* Rotate by 270 degree counterclockwise */
    CAMERA3_STREAM_ROTATION_270 = 3
} camera3_stream_rotation_t;

/**
 * camera3_stream_configuration_mode_t:
 *
 * This defines the general operation mode for the HAL (for a given stream configuration), where
 * modes besides NORMAL have different semantics, and usually limit the generality of the API in
 * exchange for higher performance in some particular area.
 */
typedef enum camera3_stream_configuration_mode {
    CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0,
    CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE = 1,
    CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000
} camera3_stream_configuration_mode_t;


typedef struct camera3_stream {
    int stream_type;
    uint32_t width;
    uint32_t height;
    int format;
    uint32_t usage;
    uint32_t max_buffers;
    void *priv;
    android_dataspace_t data_space;
    int rotation;
    void *reserved[7];
} camera3_stream_t;

typedef struct camera3_stream_configuration {
    uint32_t num_streams;
    camera3_stream_t **streams;
    uint32_t operation_mode;
} camera3_stream_configuration_t;

typedef enum camera3_buffer_status {
    CAMERA3_BUFFER_STATUS_OK = 0,
    CAMERA3_BUFFER_STATUS_ERROR = 1
} camera3_buffer_status_t;

typedef struct camera3_stream_buffer {
    camera3_stream_t *stream;
    buffer_handle_t *buffer;
    int status;
    int acquire_fence;
    int release_fence;
} camera3_stream_buffer_t;

typedef struct camera3_stream_buffer_set {
    camera3_stream_t *stream;
    uint32_t num_buffers;
    buffer_handle_t **buffers;
} camera3_stream_buffer_set_t;

typedef struct camera3_jpeg_blob {
    uint16_t jpeg_blob_id;
    uint32_t jpeg_size;
} camera3_jpeg_blob_t;

enum {
    CAMERA3_JPEG_BLOB_ID = 0x00FF
};

typedef enum camera3_msg_type {
    CAMERA3_MSG_ERROR = 1,
    CAMERA3_MSG_SHUTTER = 2,
    CAMERA3_NUM_MESSAGES
} camera3_msg_type_t;

typedef enum camera3_error_msg_code {
    CAMERA3_MSG_ERROR_DEVICE = 1,
    CAMERA3_MSG_ERROR_REQUEST = 2,
    CAMERA3_MSG_ERROR_RESULT = 3,
    CAMERA3_MSG_ERROR_BUFFER = 4,
    CAMERA3_MSG_NUM_ERRORS
} camera3_error_msg_code_t;

typedef struct camera3_error_msg {
    uint32_t frame_number;
    camera3_stream_t *error_stream;
    int error_code;
} camera3_error_msg_t;

typedef struct camera3_shutter_msg {
    uint32_t frame_number;
    uint64_t timestamp;
} camera3_shutter_msg_t;

typedef struct camera3_notify_msg {
    int type;
    union {
        camera3_error_msg_t error;
        camera3_shutter_msg_t shutter;
        uint8_t generic[32];
    } message;
} camera3_notify_msg_t;

typedef enum camera3_request_template {
    CAMERA3_TEMPLATE_PREVIEW = 1,
    CAMERA3_TEMPLATE_STILL_CAPTURE = 2,
    CAMERA3_TEMPLATE_VIDEO_RECORD = 3,
    CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4,
    CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5,
    CAMERA3_TEMPLATE_MANUAL = 6,
    CAMERA3_TEMPLATE_COUNT,
    CAMERA3_VENDOR_TEMPLATE_START = 0x40000000
} camera3_request_template_t;

typedef struct camera3_capture_request {
    uint32_t frame_number;
    const camera_metadata_t *settings;
    uint32_t num_output_buffers;
    const camera3_stream_buffer_t *output_buffers;
} camera3_capture_request_t;


typedef struct camera3_capture_result {
    uint32_t frame_number;
    const camera_metadata_t *result;
    uint32_t num_output_buffers;
    const camera3_stream_buffer_t *output_buffers;
    const camera3_stream_buffer_t *input_buffer;
    uint32_t partial_result;
} camera3_capture_result_t;

typedef struct camera3_callback_ops {
    void (*process_capture_result)(const struct camera3_callback_ops *,
            const camera3_capture_result_t *result);
    void (*notify)(const struct camera3_callback_ops *,
            const camera3_notify_msg_t *msg);
} camera3_callback_ops_t;

typedef struct camera3_device_ops {
    int (*initialize)(const struct camera3_device *,
            const camera3_callback_ops_t *callback_ops);
    int (*configure_streams)(const struct camera3_device *,
            camera3_stream_configuration_t *stream_list);
    int (*register_stream_buffers)(const struct camera3_device *,
            const camera3_stream_buffer_set_t *buffer_set);
    const camera_metadata_t* (*construct_default_request_settings)(
            const struct camera3_device *,
            int type);
    int (*process_capture_request)(const struct camera3_device *,
            camera3_capture_request_t *request);
    void (*get_metadata_vendor_tag_ops)(const struct camera3_device*,
            vendor_tag_query_ops_t* ops);
    void (*dump)(const struct camera3_device *, int fd);
    int (*flush)(const struct camera3_device *);
    /* reserved for future use */
    void *reserved[8];
} camera3_device_ops_t;

typedef struct camera3_device {
    hw_device_t common;
    camera3_device_ops_t *ops;
    void *priv;
} camera3_device_t;