1. 驱动实现原理

1.1 整体架构设计

OpenHarmony人脸识别驱动采用分层架构设计，基于HDF（Hardware Driver Foundation）框架实现，主要包括以下层次：

• 接口层（IDL定义）：定义标准化的HDI接口，提供跨进程通信能力
• 服务层（Service实现）：实现具体的业务逻辑，处理人脸识别相关操作
• 执行器层（Executor实现）：封装具体的人脸识别算法和硬件操作

1.2 核心组件

1.2.1 接口定义组件

• IFaceAuthInterface：人脸认证接口，负责获取执行器列表
• IAllInOneExecutor：一体化执行器接口，处理所有认证操作
• IExecutorCallback：异步操作回调接口，用于结果和状态通知

1.2.2 服务实现组件

• FaceAuthInterfaceService：人脸认证接口服务实现
• AllInOneExecutorImpl：一体化执行器实现

1.3 工作流程

1. 初始化阶段：驱动加载时创建FaceAuthInterfaceService实例
2. 执行器注册：服务创建AllInOneExecutorImpl实例并注册到执行器列表
3. 业务操作：上层应用通过HDI接口调用执行器的具体功能
4. 异步回调：通过IExecutorCallback接口返回操作结果

2. 驱动接口调用关系

2.1 接口调用时序

3. 实现函数源码解读

3.1 FaceAuthInterfaceService 实现

3.1.1 构造函数

FaceAuthInterfaceService::FaceAuthInterfaceService()
{
    auto executor = new (std::nothrow) AllInOneExecutorImpl();
    if (executor == nullptr) {
        IAM_LOGE("executor is nullptr");
        return;
    }
    executorList_.push_back(sptr<IAllInOneExecutor>(executor));
}

功能说明：

• 创建AllInOneExecutorImpl实例
• 将执行器添加到执行器列表中
• 提供错误处理机制

3.1.2 GetExecutorList方法

int32_t FaceAuthInterfaceService::GetExecutorList(std::vector<sptr<IAllInOneExecutor>> &executorList)
{
    IAM_LOGI("interface mock start");
    for (auto executor : executorList_) {
        executorList.push_back(executor);
    }
    IAM_LOGI("interface mock success");
    return HDF_SUCCESS;
}

功能说明：

• 遍历内部执行器列表
• 将执行器引用添加到输出参数中
• 返回操作成功状态

3.2 AllInOneExecutorImpl 实现

3.2.1 构造函数

AllInOneExecutorImpl::AllInOneExecutorImpl()
{
    executorInfo_ = {
        .sensorId = SENSOR_ID,
        .executorMatcher = EXECUTOR_TYPE,
        .executorRole = ExecutorRole::ALL_IN_ONE,
        .authType = AuthType::FACE,
        .publicKey = std::vector<uint8_t>(PUBLIC_KEY_LEN, 0),
        .extraInfo = {},
        .esl = ExecutorSecureLevel::ESL2,
        .maxTemplateAcl = FACE_CAPABILITY_LEVEL,
    };
}

功能说明：

• 初始化执行器信息结构体
• 设置传感器ID、执行器类型、认证类型等参数
• 配置安全等级和能力级别

3.2.2 Enroll方法

int32_t AllInOneExecutorImpl::Enroll(uint64_t scheduleId, const std::vector<uint8_t> &extraInfo, 
                                     const sptr<IExecutorCallback> &callbackObj)
{
    IAM_LOGI("interface mock start");
    static_cast<void>(scheduleId);
    static_cast<void>(extraInfo);
    if (callbackObj == nullptr) {
        IAM_LOGE("callbackObj is nullptr");
        return HDF_ERR_INVALID_PARAM;
    }
    IAM_LOGI("enroll, result is %{public}d", ResultCode::OPERATION_NOT_SUPPORT);
    int32_t ret = callbackObj->OnResult(ResultCode::OPERATION_NOT_SUPPORT, {});
    if (ret != HDF_SUCCESS) {
        IAM_LOGE("callback result is %{public}d", ret);
        return HDF_FAILURE;
    }
    return HDF_SUCCESS;
}

功能说明：

• 处理人脸注册请求
• 验证回调对象有效性
• 通过回调返回操作结果
• 提供完整的错误处理机制

3.2.3 Authenticate方法

int32_t AllInOneExecutorImpl::Authenticate(uint64_t scheduleId, const std::vector<uint64_t> &templateIdList,
    const std::vector<uint8_t> &extraInfo, const sptr<IExecutorCallback> &callbackObj)
{
    IAM_LOGI("interface mock start");
    static_cast<void>(scheduleId);
    static_cast<void>(templateIdList);
    static_cast<void>(extraInfo);
    if (callbackObj == nullptr) {
        IAM_LOGE("callbackObj is nullptr");
        return HDF_ERR_INVALID_PARAM;
    }
    IAM_LOGI("authenticate, result is %{public}d", ResultCode::NOT_ENROLLED);
    int32_t ret = callbackObj->OnResult(ResultCode::NOT_ENROLLED, {});
    if (ret != HDF_SUCCESS) {
        IAM_LOGE("callback result is %{public}d", ret);
        return HDF_FAILURE;
    }
    return HDF_SUCCESS;
}

功能说明：

• 处理人脸认证请求
• 支持模板列表认证
• 返回认证状态和结果

3.2.4 SendCommand方法

int32_t AllInOneExecutorImpl::SendCommand(int32_t commandId, const std::vector<uint8_t> &extraInfo, 
                                          const sptr<IExecutorCallback> &callbackObj)
{
    IAM_LOGI("interface mock start");
    static_cast<void>(extraInfo);
    if (callbackObj == nullptr) {
        IAM_LOGE("callbackObj is nullptr");
        return HDF_ERR_INVALID_PARAM;
    }
    int32_t ret;
    switch (commandId) {
        case DriverCommandId::LOCK_TEMPLATE:
            IAM_LOGI("lock template, result is %{public}d", ResultCode::SUCCESS);
            ret = callbackObj->OnResult(ResultCode::SUCCESS, {});
            break;
        case DriverCommandId::UNLOCK_TEMPLATE:
            IAM_LOGI("unlock template, result is %{public}d", ResultCode::SUCCESS);
            ret = callbackObj->OnResult(ResultCode::SUCCESS, {});
            break;
        case DriverCommandId::INIT_ALGORITHM:
            IAM_LOGI("init algorithm, result is %{public}d", ResultCode::SUCCESS);
            ret = callbackObj->OnResult(ResultCode::SUCCESS, {});
            break;
        default:
            IAM_LOGD("not support DriverCommandId : %{public}d", commandId);
            ret = callbackObj->OnResult(ResultCode::OPERATION_NOT_SUPPORT, {});
    }
    if (ret != HDF_SUCCESS) {
        IAM_LOGE("callback result is %{public}d", ret);
        return HDF_FAILURE;
    }
    return HDF_SUCCESS;
}

功能说明：

• 支持多种驱动命令操作
• 包括模板锁定、解锁、算法初始化等
• 提供命令扩展机制

4. 驱动接口版本差异说明

4.1 v1.0 版本特性

4.1.1 接口定义

• IExecutor接口：基础执行器接口
• IFaceAuthInterface接口：基础人脸认证接口
• IExecutorCallback接口：基础回调接口

4.1.2 主要功能

• 基本的注册、认证、识别、删除操作
• 简单的命令发送机制
• 基础的回调通知

4.2 v1.1 版本增强

4.2.1 新增功能

• 属性获取机制：支持获取认证子类型、锁定时长等属性
• 模板缓存：支持模板缓存功能
• SA命令回调：新增系统应用命令回调机制

4.2.2 接口扩展

// v1.1 新增方法
int32_t GetProperty(const std::vector<uint64_t> &templateIdList, 
                   const std::vector<int32_t> &propertyTypes, Property &property);
                    
int32_t SetCachedTemplates(const std::vector<uint64_t> &templateIdList);

int32_t RegisterSaCommandCallback(const sptr<ISaCommandCallback> &callbackObj);

4.3 v2.0 版本全面升级

4.3.1 架构重构

• 一体化执行器：将Collector和Verifier功能合并
• 增强的安全机制：支持更高级别的安全等级
• 扩展的消息机制：支持角色间消息传递

4.3.2 新增特性

• 消息发送机制：支持执行器间消息通信
• 增强的命令支持：扩展驱动命令类型
• 完善的回调机制：新增OnMessage回调

4.3.3 接口对比

4.4 版本演进总结

1. v1.0 → v1.1：功能增强，增加属性管理和模板缓存
2. v1.1 → v2.0：架构重构，实现一体化执行器设计
3. 兼容性保证：新版本保持向后兼容，支持平滑升级

5. 关键技术特性

5.1 异步回调机制

• 支持操作结果的异步通知
• 提供处理过程中的状态提示
• 确保UI线程不被阻塞

5.2 安全机制

• 多级安全等级支持（ESL0-ESL3）
• 模板访问控制
• 公钥加密通信

5.3 扩展性设计

• 模块化的接口设计
• 支持自定义命令扩展
• 可插拔的执行器架构

OpenHarmony人脸识别驱动通过分层架构设计和标准化的HDI接口，提供了完整的人脸识别功能支持。从v1.0到v2.0的版本演进体现了系统在功能丰富性、安全性和扩展性方面的持续改进。驱动采用异步回调机制确保系统响应性，同时通过模块化设计支持灵活的扩展和定制。