【OpenHarmony】USB服务组件

USB Manager 模块

目录

1. 模块概述
   • 1.1 功能与目标
   • 1.2 系统位置
   • 1.3 设计思路与模式
   • 1.4 系统框图
2. 模块结构
   • 2.1 源文件与头文件
   • 2.2 类、结构体、函数与方法
   • 2.3 类图
   • 2.4 模块内部依赖框图
3. 模块间交互
   • 3.1 交互描述
   • 3.2 外部依赖框图
4. 状态机转换图
   • 4.1 状态机模型
   • 4.2 状态机树图
   • 4.3 状态机切换规则
   • 4.4 状态机转换图
5. 接口设计
   • 5.1 公共接口
   • 5.2 数据交换接口
   • 5.3 接口调用时序图

1. 模块概述

源码：https://gitee.com/openharmony/usb_usb_manager

1.1 功能与目标

主要功能

USB Manager 是 OpenHarmony 系统中的 USB 服务管理模块，提供完整的 USB 设备管理能力，主要功能包括：

设计目标

1. 统一管理: 提供统一的USB设备管理接口，屏蔽底层HAL差异
2. 权限控制: 实现细粒度的USB设备访问权限控制
3. 事件驱动: 支持USB设备热插拔事件的实时通知
4. 多模式支持: 同时支持Host模式和Device模式
5. 可扩展性: 模块化设计，便于功能扩展

使用场景

• 移动设备连接USB外设（键盘、鼠标、U盘等）
• 设备作为USB从设备连接PC进行数据传输
• USB调试模式（HDC）
• 串口通信应用
• 配件模式连接

1.2 系统位置

USB Manager 在 OpenHarmony 系统中的位置如下：

┌─────────────────────────────────────────────────────────────┐ │ 应用层 (Application) │ │ JS/TS/ETS 应用程序 │ ├─────────────────────────────────────────────────────────────┤ │ 框架层 (Framework) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ USB API (NAPI) │ │ │ │ @ohos.usbManager 接口 │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 服务层 (Service) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ ★ USB Manager Service ★ │ │ │ │ ┌──────────┬──────────┬──────────┬──────────────┐ │ │ │ │ │ Host │ Device │ Port │ Serial │ │ │ │ │ │ Manager │ Manager │ Manager │ Manager │ │ │ │ │ └──────────┴──────────┴──────────┴──────────────┘ │ │ │ │ ┌──────────────────┬──────────────────────────┐ │ │ │ │ │ Right Manager │ Accessory Manager │ │ │ │ │ └──────────────────┴──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ HAL层 (Hardware Abstraction) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ USB HAL │ │ │ │ IUsbInterface / ISerialInterface │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 内核层 (Kernel) │ │ Linux USB Driver │ └─────────────────────────────────────────────────────────────┘

模块性质

• 类型: 核心系统服务模块
• SA ID: 4201 (USB_SYSTEM_ABILITY_ID)
• 运行方式: 系统能力（SystemAbility）
• 进程模型: 独立进程运行

与其他模块的关系

1.3 设计思路与模式

设计思路

1. 分层架构设计

   • API层：提供NAPI接口供JS/TS应用调用
   • Service层：实现核心业务逻辑
   • HAL层：封装硬件抽象层接口

2. 模块化设计

   • 按功能划分为Host、Device、Port、Serial等子管理器
   • 各子模块职责单一，便于维护和扩展

3. 事件驱动机制

   • 通过订阅者模式接收HAL层的设备事件
   • 使用公共事件服务广播设备状态变化

4. 权限控制机制

   • 基于数据库的权限持久化存储
   • 支持临时权限和永久权限
   • 集成系统权限框架

设计模式

1.4 系统框图

┌────────────────────────────────────────────────────────────────────────┐ │ USB API │ │ ┌────────────────────────┬─────────────────────┬──────────────────┐ │ │ │ USB FUNCTION │ USB INTERFACE │ USB ENUM │ │ │ │ • getDevices │ • USBEndpoint │ • PowerRoleType │ │ │ │ • connectDevice │ • USBInterface │ • DataRoleType │ │ │ │ • hasRight │ • USBConfig │ • PortModeType │ │ │ │ • requestRight │ • USBDevice │ • USBPortStatus │ │ │ │ • claimInterface │ • USBDevicePipe │ • FunctionType │ │ │ │ • bulkTransfer │ • USBPort │ │ │ │ │ • controlTransfer │ • USBControlParams │ │ │ │ └────────────────────────┴─────────────────────┴──────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ USB SERVICE │ │ ┌──────────────────┬──────────────────┬──────────────────────────┐ │ │ │ HOST │ DEVICE │ PORT │ │ │ │ ┌────────────┐ │ ┌────────────┐ │ ┌──────────────────┐ │ │ │ │ │ Right │ │ │ Function │ │ │ Status │ │ │ │ │ │ Manager │ │ │ Manager │ │ │ Manager │ │ │ │ │ └────────────┘ │ └────────────┘ │ └──────────────────┘ │ │ │ │ ┌────────────┐ │ ┌────────────┐ │ ┌──────────────────┐ │ │ │ │ │ Device │ │ │ Device │ │ │ Role │ │ │ │ │ │ Manager │ │ │ Manager │ │ │ Manager │ │ │ │ │ └────────────┘ │ └────────────┘ │ └──────────────────┘ │ │ │ └──────────────────┴──────────────────┴──────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ USB HAL │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ HAL (INTERFACE IUsbInterface) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────┬─────────────────────────────────────┐ │ │ │ HOST DDK │ DEVICE DDK │ │ │ └──────────────────────────┴─────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘

2. 模块结构

2.1 源文件与头文件

2.1.1 服务层核心文件 (services/native/)

2.1.2 接口层文件 (interfaces/innerkits/native/)

2.1.3 IDL接口文件 (interfaces/innerkits/)

2.1.4 工具类文件 (utils/native/)

2.2 类、结构体、函数与方法

2.2.1 核心类

UsbService 类

classUsbService:publicSystemAbility,publicUsbServerStub{DECLARE_SYSTEM_ABILITY(UsbService)DECLARE_DELAYED_SP_SINGLETON(UsbService);public:// 生命周期管理voidOnStart()override;voidOnStop()override;// Host功能接口int32_tOpenDevice(uint8_tbusNum,uint8_tdevAddr);int32_tClose(uint8_tbusNum,uint8_tdevAddr);int32_tGetDevices(std::vector<UsbDevice>&deviceList);int32_tClaimInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_tforce);int32_tReleaseInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid);int32_tBulkTransferRead(...);int32_tBulkTransferWrite(...);int32_tControlTransfer(...);// Device功能接口int32_tGetCurrentFunctions(int32_t&funcs);int32_tSetCurrentFunctions(int32_tfuncs);// Port功能接口int32_tGetPorts(std::vector<UsbPort>&ports);int32_tSetPortRole(int32_tportId,int32_tpowerRole,int32_tdataRole);// 权限管理接口boolHasRight(conststd::string&deviceName);int32_tRequestRight(conststd::string&deviceName);int32_tRemoveRight(conststd::string&deviceName);// Serial功能接口int32_tSerialOpen(int32_tportId,constsptr<IRemoteObject>&serialRemote);int32_tSerialClose(int32_tportId);int32_tSerialRead(...);int32_tSerialWrite(...);private:std::shared_ptr<UsbHostManager>usbHostManager_;std::shared_ptr<UsbDeviceManager>usbDeviceManager_;std::shared_ptr<UsbPortManager>usbPortManager_;std::shared_ptr<UsbRightManager>usbRightManager_;std::shared_ptr<UsbAccessoryManager>usbAccessoryManager_;std::shared_ptr<SERIAL::SerialManager>usbSerialManager_;sptr<HDI::Usb::V1_2::IUsbInterface>usbd_;};

UsbHostManager 类

classUsbHostManager{public:explicitUsbHostManager(SystemAbility*systemAbility);~UsbHostManager();// 设备管理voidGetDevices(MAP_STR_DEVICE&devices);boolAddDevice(UsbDevice*dev);boolDelDevice(uint8_tbusNum,uint8_tdevNum);// 设备操作int32_tOpenDevice(uint8_tbusNum,uint8_tdevAddr);int32_tClose(uint8_tbusNum,uint8_tdevAddr);int32_tResetDevice(uint8_tbusNum,uint8_tdevAddr);// 接口操作int32_tClaimInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_tforce);int32_tReleaseInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterface);int32_tSetInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_taltIndex);// 数据传输int32_tBulkTransferRead(...);int32_tBulkTransferWrite(...);int32_tControlTransfer(...);int32_tRequestQueue(...);int32_tRequestWait(...);// 策略执行voidExecuteStrategy(UsbDevice*devInfo);int32_tManageGlobalInterface(booldisable);int32_tManageDevice(int32_tvendorId,int32_tproductId,booldisable);private:MAP_STR_DEVICE devices_;SystemAbility*systemAbility_;std::mutex mutex_;sptr<HDI::Usb::V1_2::IUsbInterface>usbd_;};

UsbDeviceManager 类

classUsbDeviceManager{public:UsbDeviceManager();int32_tInit();// Function管理staticuint32_tConvertFromString(std::string_view funcs);staticstd::stringConvertToString(uint32_tfunc);staticboolIsSettableFunctions(int32_tfuncs);voidUpdateFunctions(int32_tfunc);int32_tGetCurrentFunctions();int32_tGetCurrentFunctions(int32_t&funcs);int32_tSetCurrentFunctions(int32_tfuncs);// 事件处理voidHandleEvent(int32_tstatus);voidSetPhyConnectState(boolphyConnect);boolIsGadgetConnected(void);// 调试接口voidDump(int32_tfd,conststd::vector<std::string>&args);private:int32_tcurrentFunctions_;boolconnected_;boolgadgetConnected_;sptr<HDI::Usb::V1_0::IUsbInterface>usbd_;std::mutex functionMutex_;};

UsbPortManager 类

classUsbPortManager{public:UsbPortManager();~UsbPortManager();voidInit();// 端口查询int32_tGetPorts(std::vector<UsbPort>&ports);int32_tGetSupportedModes(int32_tportId,int32_t&supportedModes);int32_tQueryPort();// 端口设置int32_tSetPortRole(int32_tportId,int32_tpowerRole,int32_tdataRole);voidUpdatePort(int32_tportId,int32_tpowerRole,int32_tdataRole,int32_tmode);voidAddPort(UsbPort&port);voidRemovePort(int32_tportId);private:std::mutex mutex_;std::map<int32_t,UsbPort>portMap_;std::map<int32_t,int32_t>supportedModeMap_;sptr<HDI::Usb::V1_0::IUsbInterface>usbd_;};

UsbRightManager 类

classUsbRightManager{public:int32_tInit();// 权限查询boolHasRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);// 权限申请int32_tRequestRight(conststd::string&busDev,conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);// 权限管理boolAddDeviceRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);boolRemoveDeviceRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);int32_tCancelDeviceRight(...);boolRemoveDeviceAllRight(conststd::string&deviceName);// 权限清理int32_tCleanUpRightExpired(std::vector<std::string>&devices);staticint32_tCleanUpRightUserDeleted(int32_t&totalUsers,int32_t&deleteUsers);staticint32_tCleanUpRightAppUninstalled(int32_tuid,conststd::string&bundleName);// 权限校验boolIsSystemAppOrSa();boolVerifyPermission();int32_tHasSetFuncRight(int32_tfunctions);private:std::mutex dialogRunning_;sptr<UsbAbilityConn>usbAbilityConn_;};

2.2.2 核心数据结构

UsbDevice 结构

classUsbDevice:publicParcelable{public:// 构造函数UsbDevice(std::string name,std::string manufacturerName,std::string productName,std::string version,uint8_tdevAddr,uint8_tbusNum,int32_tvendorId,int32_tproductId,int32_tbaseClass,int32_tsubClass,int32_tprotocol,std::vector<USBConfig>configs);// 序列化接口boolMarshalling(Parcel&parcel)constoverride;staticUsbDevice*Unmarshalling(Parcel&data);// 属性访问器conststd::string&GetName()const;conststd::string&GetManufacturerName()const;conststd::string&GetProductName()const;int32_tGetVendorId()const;int32_tGetProductId()const;int32_tGetClass()const;uint8_tGetBusNum()const;uint8_tGetDevAddr()const;std::vector<USBConfig>&GetConfigs();private:std::string name_;std::string manufacturerName_;std::string productName_;std::string version_;std::string serial_;uint8_tdevAddr_;uint8_tbusNum_;int32_tvendorId_;int32_tproductId_;int32_tbaseClass_;int32_tsubClass_;int32_tprotocol_;std::vector<USBConfig>configs_;};

UsbPort 结构

structUsbPortStatus{int32_tcurrentMode;// 当前模式int32_tcurrentPowerRole;// 当前电源角色int32_tcurrentDataRole;// 当前数据角色};structUsbPort:publicParcelable{int32_tid;// 端口IDint32_tsupportedModes;// 支持的模式UsbPortStatus usbPortStatus;// 端口状态boolMarshalling(Parcel&parcel)constoverride;staticUsbPort*Unmarshalling(Parcel&data);};

错误码枚举

enumUsbErrCode{UEC_OK=0,// 接口层错误UEC_INTERFACE_NO_MEMORY,UEC_INTERFACE_INVALID_OPERATION,UEC_INTERFACE_INVALID_VALUE,UEC_INTERFACE_PERMISSION_DENIED,// 服务层错误UEC_SERVICE_NO_MEMORY,UEC_SERVICE_INVALID_OPERATION,UEC_SERVICE_INVALID_VALUE,UEC_SERVICE_PERMISSION_DENIED,UEC_SERVICE_PERMISSION_DENIED_SYSAPI,// 串口错误UEC_SERIAL_PORT_REPEAT_OPEN,UEC_SERIAL_PORT_REPEAT_CLOSE,UEC_SERIAL_PORT_NOT_OPEN,UEC_SERIAL_IO_EXCEPTION,};

2.3 类图

2.4 模块内部依赖框图

3. 模块间交互

3.1 交互描述

3.1.1 与HAL层的交互

USB Manager 通过 HDI (Hardware Device Interface) 与 USB HAL 层进行交互：

3.1.2 与系统服务的交互

3.1.3 异步处理机制

3.1.4 多线程处理

USB Manager 使用以下多线程机制：

1. 主线程: 处理IPC请求
2. 事件处理线程: 处理HAL层事件回调
3. 定时器线程: 处理超时和延迟任务
4. 回调线程: 处理异步传输回调

// 线程安全保护示例classUsbService{private:std::mutex mutex_;// 主互斥锁std::mutex serialPidVidMapMutex_;// 串口映射锁// 子管理器各自维护独立的锁// UsbHostManager::mutex_// UsbPortManager::mutex_// SerialManager::serialPortMapMutex_};

3.2 外部依赖框图

4. 状态机转换图

4.1 状态机模型

USB Manager 包含多个状态机，分别管理不同的功能模块：

1. USB Service 状态机: 管理服务生命周期
2. USB Device 状态机: 管理Device模式连接状态
3. USB Accessory 状态机: 管理配件模式状态
4. USB Port 状态机: 管理端口角色状态

4.2 状态机树图

4.3 状态机切换规则

4.3.1 UsbService 状态切换

4.3.2 UsbDevice 状态切换

4.3.3 UsbAccessory 状态切换

4.4 状态机转换图

UsbService 状态转换图

UsbDevice 状态转换图

UsbAccessory 状态转换图

UsbPort 状态转换图

5. 接口设计

5.1 公共接口

5.1.1 Host 功能接口

5.1.2 Device 功能接口

5.1.3 Port 功能接口

5.1.4 权限管理接口

5.1.5 Serial 功能接口

5.2 数据交换接口

5.2.1 IPC 接口定义 (IUsbServer.idl)

interface OHOS.USB.IUsbServer { // Host功能 [macrodef USB_MANAGER_FEATURE_HOST] void GetDevices([out]UsbDevice[] deviceList); [macrodef USB_MANAGER_FEATURE_HOST] void OpenDevice([in]unsigned char busNum, [in]unsigned char devAddr); [macrodef USB_MANAGER_FEATURE_HOST] void Close([in]unsigned char busNum, [in]unsigned char devAddr); [macrodef USB_MANAGER_FEATURE_HOST] void BulkTransferRead([in]unsigned char busNum, [in]unsigned char devAddr, [in]USBEndpoint ep, [out]UsbBulkTransData buffData, [in]int timeOut); [macrodef USB_MANAGER_FEATURE_HOST] void ControlTransfer([in]unsigned char busNum, [in]unsigned char devAddr, [in]UsbCtlSetUp ctrlParams, [inout]unsigned char[] bufferData); // Device功能 [macrodef USB_MANAGER_FEATURE_DEVICE] void GetCurrentFunctions([out] int funcs); [macrodef USB_MANAGER_FEATURE_DEVICE] void SetCurrentFunctions([in] int funcs); // Port功能 [macrodef USB_MANAGER_FEATURE_PORT] void GetPorts([out]UsbPort[] ports); [macrodef USB_MANAGER_FEATURE_PORT] void SetPortRole([in] int portId, [in] int powerRole, [in] int dataRole); // Serial功能 void SerialOpen([in] int portId, [in] IRemoteObject serialRemote); void SerialClose([in] int portId); void SerialRead([in] int portId, [out]unsigned char[] buffData, [in]unsigned int size, [out]unsigned int actualSize, [in]unsigned int timeout); void SerialWrite([in] int portId, [in]unsigned char[] buffData, [in]unsigned int size, [out]unsigned int actualSize, [in]unsigned int timeout); }

5.2.2 数据结构序列化

所有跨进程传输的数据结构都实现了Parcelable接口：

// UsbDevice 序列化boolUsbDevice::Marshalling(Parcel&parcel)const{WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Uint8,parcel,this->busNum_);WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Uint8,parcel,this->devAddr_);WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Int32,parcel,this->vendorId_);WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Int32,parcel,this->productId_);// ... 其他字段returntrue;}// UsbPort 序列化boolUsbPort::Marshalling(Parcel&parcel)const{WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Int32,parcel,this->id);WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Int32,parcel,this->supportedModes);WRITE_PARCEL_AND_RETURN_FALSE_WHEN_FAIL(Int32,parcel,this->usbPortStatus.currentMode);// ... 其他字段returntrue;}

5.3 接口调用时序图

5.3.1 设备打开与数据传输时序

5.3.2 设备插拔事件处理时序

5.3.3 Function切换时序

附录

A. 错误码说明

B. 功能位域定义

C. 端口角色定义