鸿蒙OpenHarmony【外设驱动使用之USB】子系统

羊村你嘻哥

已于 2024-10-21 21:57:30 修改

阅读量1.4k

点赞数 13

分类专栏：山海经文章标签： harmonyos 华为驱动开发鸿蒙鸿蒙系统 usb

于 2024-10-21 20:42:49 首次发布

本文链接：https://blog.csdn.net/zxc95279527q/article/details/143129506

版权

USB

概述

功能简介

USB（Universal Serial Bus）通用串行总线，包含了主机端（Host）和设备端（Device）。主机端负责USB总线中的数据传输及端口管理，设备端则可以连接各种外设，所以USB驱动开发又分为主机端驱动开发和设备端驱动开发。

OpenHarmony系统USB模块支持USB业务的开发，提供USB相关的功能，提供用户态第三方功能驱动的USB设备数据读写接口，以及提供创建和删除USB设备，接口的事件获取、打开和关闭等，管道同步异步读写通信，设置USB自定义属性等。

USB DDK（USB DriverDevelop Kit）是HDF驱动框架为开发者提供的USB驱动程序开发套件，包括USB Host DDK及USB Device DDK两部分，支持基于用户态开发USB设备驱动的同时，还提供了丰富的USB驱动开发能力，让广大开发者能精准且高效的开发USB驱动程序。

基本概念

管道

管道（Pipe）是主机端和设备端点之间数据传输的模型。任何USB设备一旦上电就存在一个信息管道，即默认的控制管道，USB主机通过该管道来获取设备的描述、配置、状态，并对设备进行配置；管道和端点关联，两者有相同的属性，如支持的传输类型、最大包长度、传输方向等。
端点

端点（Endpoint）是USB设备中的可以进行数据收发的最小单元，支持单向或者双向的数据传输。一个USB设备可以包括若干个端点，不同的端点以端点编号和方向区分。不同端点可以支持不同的传输类型、访问间隔以及最大数据包大小。除端点0外，所有的端点只支持一个方向的数据传输。端点0是一个特殊的端点，它支持双向的控制传输。
接口

应用软件通过和设备之间的数据交换来完成设备的控制和数据传输。由于同一管道只支持一种类型的数据传输，因此这个过程中通常需要多个管道来完成数据交换。像这样用在一起来对设备进行控制的若干管道的集合称为接口。
描述符

描述符（Descriptor）是用于描述设备属性（Attributes）的数据结构，第一个字节表示描述符的大小（字节数），第二个字节表示描述符的类型（Type）。

运作机制

USB Host DDK

USB Host DDK为开发者提供了主机端USB驱动开发能力，按照功能分为三大类，分别是DDK初始化类、interface对象操作类及request对象操作类。

图1 USB Host驱动模型图

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

USB Interface Pool负责USB Interface管理。提供USB Interface接口对象的申请和回收，USB Interface接口对象用来记录设备端口信息以及资源。USB Interface Pool按照USB Port对USB Interface进行分类管理。同时，此模块还提供了USB DDK API，方便开发者进行USB数据读写操作。
USB Protocol Layer提供USB协议封装，根据USB协议对设备IO/控制命令进行翻译和解析”，同时负责设备描述符的管理，根据USB Device上报的枚举信息，匹配对应的描述符；构建对应的USB Interface接口对象，并将其加入到USB Interface Pool中管理。
Device IO Manager负责USB IO请求管理，提供了同步IO和异步IO管理机制，对于异步IO，IO Manager负责将该请求记录下来，然后通过Raw API Library提供的接口依次处理待发送的IO请求；当收到USB控制器应答的处理结果后，IO接收线程负责解析并上报处理结果给上层调用者。
Raw API Library抽象了底层OS能力，定义了统一的OS能力接口，对外提供了USB RAW API，方便开发者实现更加复杂的驱动功能。
OS Adapter用于封装与平台（Linux和LiteOS）相关的操作，根据不同平台配置编译对应平台的封装接口。在Linux平台上，访问USB FS的操作，全部都封装在这个模块中；而在LiteOS平台上，基于FreeBSD USB框架的设备访问操作，也都全部封装在这个模块中。
PNP Notify用于动态监测USB状态变化，当有新设备添加/移除时，变化设备信息。同时将所有USB设备信息都通过KHDF上报给UHDF侧的PNP Notify Manager模块来完成加载/卸载第三方功能驱动。

USB Device DDK

USB Device DDK向开发者提供了设备端USB驱动开发能力。例如，USB端口动态注册和去注册能力，开发者可以基于能力实现USB端口的动态添加和组合；动态实例化能力，支持根据动态下发设备、配置、接口及端点描述符创建设备实例及传输通道；用户态的数据发送及接收能力，支持用户态下发送及接收数据；复合设备能力，支持一个物理设备上多个逻辑设备，实现多个逻辑设备间隔离，并支持不同逻辑设备同时被不同的应用进程访问。

图2 USB Device驱动模型图

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

SDK IF负责将USB设备按照设备、接口、管道进行逻辑划分，对配置管理、设备管理、IO管理进行封装。此模块还向开发者提供了设备创建、获取接口、接收Event事件、收发数据等设备测驱动开发的能力接口。
Configuration Manager负责解析HCS文件描述的USB描述符信息，得到的USB描述符信息用于设备创建，同时模块还提供了自定义属性的读取、创建、删除、修改等操作。
Device Manager负责根据配置模块解析USB描述符，并根据USB描述符创建设备。同时还负责获取设备、删除设备、获取设备状态，获取设备上面接口信息。
IO Manager负责数据的读写，包括Events事件、数据读写完成后事件的接收，支持同步和异步模式数据读写。
Adapter IF主要是对复合设备配置驱动及通用功能驱动设备节点操作进行封装，为上层提供统一的设备管理接口。
Adapter该模块由复合设备配置驱动及通用功能驱动提供。

开发指导

由于内核态开发USB驱动较复杂，需要开发者对USB协议要有较深的了解才能很好的使用，对开发者的要求相对较高。USB DDK的引入是为了让开发者能在用户态更方便的开发USB驱动。

场景介绍

USB Host DDK为开发者提供了普通模式和专家模式，普通模式下，开发者可通过USB DDK API直接完成相关USB数据读写操作，不需要过多关注底层的传输细节。专家模式下，开发者通过USB RAW API直接访问OS平台中USB通道的接口，自定义实现更加复杂的功能。USB Device DDk为开发者提供了管理USB设备、接口定义及USB数据请求等功能。下文将介绍相关API。

接口说明

USB主机端驱动程序开发相关接口（普通模式）如下

表1 USB主机端驱动程序开发相关接口（普通模式）

接口名称	功能描述
int32_t UsbInitHostSdk(struct UsbSession **session);	USB主机端驱动开发工具包初始化
struct UsbInterface UsbClaimInterface(const struct UsbSession session, uint8_t busNum, uint8_t usbAddr, uint8_t interfaceIndex)	获取USB接口对象
UsbInterfaceHandle UsbOpenInterface(const struct UsbInterface interfaceObj);	打开USB对象接口
int32_t UsbGetPipeInfo(const UsbInterfaceHandle interfaceHandle, uint8_t settingIndex, uint8_t pipeId, struct UsbPipeInfo pipeInfo);	获取指定可选设置的管道信息
struct UsbRequest UsbAllocRequest(const UsbInterfaceHandle interfaceHandle, int32_t isoPackets , int32_t length);	分配请求对象
int32_t UsbFillRequest(const struct UsbRequest request, const UsbInterfaceHandle interfaceHandle, const struct UsbRequestParams *params);	填充请求
int32_t UsbSubmitRequestSync(const struct UsbRequest *request);	发送同步请求

USB主机端驱动程序开发相关接口（专家模式）如下

表2 USB主机端驱动程序开发相关接口（专家模式）

接口名称	功能描述
int32_t UsbRawInit(struct UsbSession **session);	USB驱动开发工具包专家模式初始化
UsbRawHandle UsbRawOpenDevice(const struct UsbSession session, uint8_t busNum, uint8_t usbAddr);	打开USB设备对象
int32_t UsbRawSendControlRequest(const struct UsbRawRequest request, const UsbRawHandle devHandle, const struct UsbControlRequestData *requestData);	执行同步控制传输
int32_t UsbRawSendBulkRequest(const struct UsbRawRequest request, const UsbRawHandle devHandle, const struct UsbRequestData *requestData);	执行同步批量传输
int32_t UsbRawSendInterruptRequest(const struct UsbRawRequest request, const UsbRawHandle devHandle, const struct UsbRequestData *requestData);	执行同步中断传输
int32_t UsbRawGetConfigDescriptor(const UsbRawDevice rawDev, uint8_t configIndex, struct UsbRawConfigDescriptor *config);	获取给定设备指定ID的设备配置描述符
int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest request, const UsbRawHandle devHandle, const struct UsbRawFillRequestData *fillData);	填充中断传输请求所需信息
int32_t UsbRawFillIsoRequest(const struct UsbRawRequest request, const UsbRawHandle devHandle, const struct UsbRawFillRequestData *fillData);	填充同步传输（Isochronous Transfers）请求所需信息
int32_t UsbRawSubmitRequest(const struct UsbRawRequest *request);	提交一个传输请求
int32_t UsbRawCancelRequest(const struct UsbRawRequest *request);	取消一个传输请求
int32_t UsbRawHandleRequests(const UsbRawHandle *devHandle);	传输请求事件完成处理

USB设备端用于管理USB设备的相关接口如下
表3 USB设备端用于管理USB设备的相关接口

接口名称	功能描述
const struct UsbFnDevice UsbFnCreateDevice(const char udcName, const struct UsbFnDescriptorData *descriptor);	创建USB设备
int32_t UsbFnRemoveDevice(struct UsbFnDevice *fnDevice);	删除USB设备
const struct UsbFnDevice UsbFnGetDevice(const char udcName);	获取USB设备

USB设备端用于USB接口定义的相关接口如下

表4 USB设备端用于USB接口定义的相关接口

接口名称	功能描述
int32_t UsbFnStartRecvInterfaceEvent(struct UsbFnInterface interface, uint32_t eventMask, UsbFnEventCallback callback, void context);	开始接受Event事件
int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface);	停止接受Event事件
UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface);	打开一个接口
int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle);	关闭一个接口
int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface interface, uint8_t pipeId, struct UsbFnPipeInfo info);	获取管道信息
int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface interface, const char name, const char *value);	设置自定义属性

USB设备端用于管理USB数据请求的相关接口如下

表5 USB设备端用于管理USB数据请求的相关接口

接口名称	功能描述
struct UsbFnRequest *UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle, uint32_t len);	申请一个控制请求
struct UsbFnRequest *UsbFnAllocRequest(UsbFnInterfaceHandle handle, uint8_t pipe, uint32_t len);	申请一个数据请求
int32_t UsbFnFreeRequest(struct UsbFnRequest *req);	释放一个请求
int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest *req);	发送异步请求
int32_t UsbFnSubmitRequestSync(struct UsbFnRequest *req, uint32_t timeout);	发送同步请求
int32_t UsbFnCancelRequest(struct UsbFnRequest *req);	取消请求

开发步骤

USB驱动基于HDF框架、Platform和OSAL基础接口进行开发，不区分操作系统和芯片平台，为不同USB器件提供统一的驱动模型。此处以串口为例，分别介绍USB Host和USB Device驱动开发的详细过程。

Host DDK API驱动开发

在设备私有数据HCS中配置，完成主机端驱动总体信息的配置，具体如下：

root {
    module = "usb_pnp_device";
    usb_pnp_config {
        match_attr = "usb_pnp_match";
        usb_pnp_device_id = "UsbPnpDeviceId";
        UsbPnpDeviceId {
            idTableList = [
                "host_acm_table"
            ];
            host_acm_table {
                // 驱动模块名，该字段的值必须和驱动入口结构的moduleName一致
                moduleName = "usbhost_acm";
                // 驱动对外发布服务的名称，必须唯一
                serviceName = "usbhost_acm_pnp_service";
                // 驱动私有数据匹配关键字
                deviceMatchAttr = "usbhost_acm_pnp_matchAttr";
                // 从该字段开始（包含该字段）之后数据长度，以byte为单位
                length = 21;
                // USB驱动匹配规则vendorId+productId+interfaceSubClass+interfaceProtocol+interfaceNumber
                matchFlag = 0x0303;
                // 厂商编号
                vendorId = 0x12D1;
                // 产品编号
                productId = 0x5000;
                // 设备出厂编号，低16位
                bcdDeviceLow = 0x0000;
                // 设备出厂编号，高16位
                bcdDeviceHigh = 0x0000;
                // USB分配的设备类代码
                deviceClass = 0;
                // USB分配的子类代码
                deviceSubClass = 0;
                // USB分配的设备协议代码
                deviceProtocol = 0;
                // 接口类型，根据实际需要可填写多个
                interfaceClass = [0];
                // 接口子类型，根据实际需要可填写多个
                interfaceSubClass = [2, 0];
                // 接口所遵循的协议，根据实际需要可填写多个    
                interfaceProtocol = [1, 2];
                // 接口的编号，根据实际需要可填写多个
                interfaceNumber = [2, 3];
            }
        }
    }
}

USB主机端驱动开发工具包初始化。

int32_t UsbInitHostSdk(struct UsbSession **session);

步骤2初始化完后获取UsbInterface对象。

const struct UsbInterface *UsbClaimInterface(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr, uint8_t interfaceIndex);

打开步骤3获取到的UsbInterface接口对象，获取相应接口的UsbInterfaceHandle对象。
```
UsbInterfaceHandle *UsbOpenInterface(const struct UsbInterface *interfaceObj);
```

根据步骤4获取到的UsbInterfaceHandle对象，获取指定索引为pipeIndex的pipeInfo信息。

int32_t UsbGetPipeInfo(const UsbInterfaceHandle *interfaceHandle, uint8_t settingIndex, uint8_t pipeId, struct UsbPipeInfo *pipeInfo);

为步骤4获取到的UsbInterfaceHandle预先分配待发送的IO Request对象。

struct UsbRequest *UsbAllocRequest(const UsbInterfaceHandle *interfaceHandle, int32_t isoPackets, int32_t length);

根据输入参数params填充步骤6预先分配的IO Request。

int32_t UsbFillRequest(const struct UsbRequest *request, const UsbInterfaceHandle *i

最低0.47元/天解锁文章