返回发烧友论坛
发 帖  

[文章]HarmonyOS USB DDK助你轻松实现USB驱动开发

HarmonyOS开发者社区
2022-03-28 19:31:18
阅读量0
HarmonyOS硬件开发
0
0

HDF（Hardware Driver Foundation）驱动框架是HarmonyOS硬件生态开放的基础，为开发者提供了驱动加载、驱动服务管理和驱动消息机制等驱动能力，让开发者能精准且高效地开发驱动程序。

本期，我们将为大家带来HDF驱动框架中USB DDK的解析与指导。

一、USB DDK介绍

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

由于基于内核态开发的USB驱动功能扩展性较差，目前开发者通常选择Libu***库进行USB驱动开发。该库是一种跨平台的用户态开源USB通信库，可以满足开发者基于用户态开发功能驱动的需求。但是，由于Libu***库是完全按照USB协议来封装接口的，所以需要开发者对USB协议要有较深的了解才能很好的使用，对开发者的要求相对较高，让很多比较初级的开发者望而却步。为了让更多的开发者都能进行基于用户态的USB驱动开发，HDF引入了USB DDK开发套件。

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

下面，我们将一一道来。  

1）USB Host DDK

USB Host DDK给开发者提供了主机端USB驱动开发能力，按照功能分类三大类,分别是DDK初始化类、interface对象操作类及request对象操作类。并为开发者提供了普通模式和专家模式两种开发模式。普通模式下，开发者可通过USBDDK API直接完成相关USB数据读写操作，不需要过多关注底层传输细节。

专家模式下，开发者通过USB RAW API直接访问OS平台USB通道的接口，自定义实现更加复杂的功能。目的是给驱动层留有更灵活，更强大的扩展方案，同时也能够兼容现有驱动，便于移植。USBHost DDK架构如图1所示：

图1 USB Host DDK架构

（1）USB Interface Pool负责USBInterface管理。提供USB Interface申请和回收，USB Interface记录设备端口信息以及资源。USB Interface Pool按照USB Port对USB Interface进行分类管理。同时，此模块还提供了USB DDK API，方便开发者USB数据读写操作。

（2）USB Protocol Layer提供USB协议封装，根据USB协议对设备IO/控制命令的“翻译/解析”，同时负责设备描述符的管理，根据USB Device上报的枚举信息，匹配对应的描述符，并构建对应的USB Interface，并加入到USB Interface Pool中管理。

（3）Device IO Manager负责USBIO请求管理，提供了同步IO和异步IO管理机制，对于异步IO，IO Manager负责将该请求记录下来，然后通过Raw API Library提供的接口依次处理待发送的IO请求；当收到USB控制器应答的处理结果后，IO接收线程负责解析并上报处理结果给上层调用者。

（4）Raw API Library抽象了底层OS能力，定义了统一的OS能力接口，对外提供了USB RAW API，让开发者自定义实现更加复杂的驱动功能。

（5）OS Adapter用于封装与平台（Linux和LiteOS）相关的操作，根据不同平台配置编译对应平台的封装接口。在Linux平台上，访问USBFS的操作，全部都封装在这个模块中；而在LiteOS平台上，基于FreeBSD USB框架的设备访问操作，对应的也都全部封装在这个模块中。

（6）PNP Notify用于动态监测USB状态变化，当有新设备添加/移除时，变化设备信息。同时将所有USB设备信息都通过KHDF上报给UHDF侧的PNPNotify Manager模块来完成加载/卸载第三方功能驱动。

2）USB Device DDK

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

USB Device DDK架构如图2所示：

图2 USB Device DDK架构

（1）SDK IF负责将USB设备按照设备、接口、管道进行逻辑划分，对配置管理、设备管理、IO管理进行封装。此模块还向开发者提供了设备创建、获取接口、接收Event事件、收发数据等设备测驱动开发的能力接口。

（2）Configuration Manager负责解析HCS文件描述的USB描述符信息，得到的USB描述符信息用于设备创建，同时模块还提供了自定义属性的读取、创建、删除、修改等操作。

（3）Device Manager负责根据配置模块解析的USB描述符，并根据USB描述符创建设备。同时模块还负责获取设备、删除设备、获取设备状态，获取设备上面接口信息。

（4）IO Manager负责数据的读写，包括Events事件、数据读写完成事件的接受，支持同步和异步模式数据读写。

（5）Adapter IF主要是对复合设备配置驱动及通用功能驱动设备节点操作进行封装，为上层提供统一的设备管理接口。

（6）Adapter该模块由复合设备配置驱动及通用功能驱动提供。  

二、USB DDK开发指导

相信大家已对USB DDK已经有了一定的认识。下面，我们来看看如何使用USB DDK来开发USB Host和USB Device驱动程序吧。

1）USB Host的开发

USB Host（主机端驱动）主要完成协议封装、设备管理、驱动安装与卸载等。通过上文的介绍，开发者可通过USB DDK API和USB RAW API来实现主机端驱动。

1. USB DDK API的使用

USB DDK API主要实现主机端USB数据读写操作，如图3所示，是USB DDK API提供的部分接口。                                             

图3 USB DDK API部分接口

使用步骤如下：

(1) 配置驱动匹配表，完成主机端驱动总体信息的配置，具体如下：
  1. struct U***PnpMatchIdTable {
  2. //驱动模块名，该字段的值必须和驱动入口结构的moduleName一致
  3. const char *moduleName;
  4. //驱动对外发布服务的名称，必须唯一
  5. const char *serviceName;
  6. //驱动私有数据匹配关键字
  7. const char *deviceMatchAttr;
  8. //从该字段开始（包含该字段）之后数据长度，以byte为单位
  9. uint8_t length;
  10. //USB驱动匹配规则
  11. uint16_t matchFlag;
  12. //厂商编号
  13. uint16_t vendorId;
  14. //产品编号
  15. uint16_t productId;
  16. //设备出厂编号，低16位
  17. uint16_t bcdDeviceLow;
  18. //设备出厂编号，高16位
  19. uint16_t bcdDeviceHigh;  
  20. //USB分配的设备类代码
  21. uint8_t deviceClass;
  22. //USB分配的子类代码
  23. uint8_t deviceSubClass;
  24. //USB分配的设备协议代码
  25. uint8_t deviceProtocol;
  26. //接口类型，根据实际需要可填写多个
  27. uint8_t interfaceClass[USB_PNP_INFO_MAX_INTERFACES];
  28. //接口子类型，根据实际需要可填写多个
  29. uint8_t interfaceSubClass[USB_PNP_INFO_MAX_INTERFACES];
  30. //接口所遵循的协议，根据实际需要可填写多个
  31. uint8_t interfaceProtocol[USB_PNP_INFO_MAX_INTERFACES];
  32. //接口的编号，根据实际需要可填写多个
  33. uint8_t interfaceNumber[USB_PNP_INFO_MAX_INTERFACES];
  34. };
复制代码

其中matchFlag表示驱动匹配规则，每个bit表示一种匹配方式，其取值如下：
  1. enum {
  2.     USB_PNP_NOTIFY_MATCH_VENDOR = 0x0001,
  3.     USB_PNP_NOTIFY_MATCH_PRODUCT = 0x0002,
  4.     USB_PNP_NOTIFY_MATCH_DEV_LOW = 0x0004,
  5.     USB_PNP_NOTIFY_MATCH_DEV_HIGH = 0x0008,
  6.     USB_PNP_NOTIFY_MATCH_DEV_CLASS = 0x0010,
  7.     USB_PNP_NOTIFY_MATCH_DEV_SUBCLASS = 0x0020,
  8.     USB_PNP_NOTIFY_MATCH_DEV_PROTOCOL = 0x0040,
  9.     USB_PNP_NOTIFY_MATCH_INT_CLASS = 0x0080,
  10.     USB_PNP_NOTIFY_MATCH_INT_SUBCLASS = 0x0100,
  11.     USB_PNP_NOTIFY_MATCH_INT_PROTOCOL = 0x0200,
  12.     USB_PNP_NOTIFY_MATCH_INT_NUMBER = 0x0400,
  13. };
复制代码

(2) USB主机端驱动开发工具包初始化，使用如下接口：
  1. int32_t U***InitHostSdk(struct U***Session **session)
复制代码

(3) 待步骤2初始化完后获取U***Interface对象，使用如下接口：
  1. const struct U***Interface *U***ClaimInterface(const struct U***Session *session, uint8_t busNum, uint8_t u***Addr, uint8_t interfaceIndex);
复制代码

(4) 打开步骤3获取到的U***Interface接口对象，获取对应接口的U***InterfaceHandle对象，使用如下接口：
  1. U***InterfaceHandle *U***OpenInterface(const struct U***Interface *interfaceObj);
复制代码

(5) 根据步骤4获取到的U***InterfaceHandle对象，获取指定索引为pinpeIndex的pipeInfo信息，使用如下接口：
  1. int32_t U***GetPipeInfo(const U***InterfaceHandle *interfaceHandle, uint8_t settingIndex, uint8_t pipeId, struct U***PipeInfo *pipeInfo);
复制代码

(6) 为步骤4获取到的U***InterfaceHandle预先分配待发送的IO Request对象，使用如下接口：
  1. struct U***Request *U***AllocRequest(const U***InterfaceHandle *interfaceHandle, int isoPackets, int length);
复制代码

(7) 根据输入参数params填充步骤6预先分配的IO Request，使用如下接口：
  1. int32_t U***FillRequest(const struct U***Request *request, const U***InterfaceHandle *interfaceHandle, const struct U***RequestParams *params);
复制代码

(8) 提交IO Request对象，可以选择同步或异步两种模式，使用如下接口：
  1. int32_t U***SubmitRequestSync(const struct U***Request *request);//发送同步IO请求
  2. int32_t U***SubmitRequestAsync(const struct U***Request *request);//发送异步IO请求
复制代码

2. USB RAW API 的使用

USB RAW API主要实现USB更加复杂的功能，如获取描述符信息、获取设备指针、复位设备、提交传输请求等，如图4所示，是USB RAW API提供的部分接口。

图4 USB RAW API

使用步骤如下：

(1) 同USB DDK API的步骤1一样，需先进行驱动匹配表配置。

(2) 初始化Host RAW，使用如下接口：
  1. int32_t U***RawInit(struct U***Session **session);
复制代码

(3) 待步骤2完成后打开USB设备，使用如下接口：
  1. U***RawHandle *U***RawOpenDevice(const struct U***Session *session, uint8_t busNum, uint8_t u***Addr);
复制代码

(4) 待步骤3完成后获取描述符，通过描述符获取接口、端点信息，使用如下接口：
  1. int32_t U***RawGetConfigDescriptor(const U***RawDevice *rawDev, uint8_t configIndex, struct U***RawConfigDescriptor **config);
复制代码

(5) 分配Request，并根据不同的传输类型使用相应的接口对Request进行填充：
  1. int32_t U***RawFillBulkRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RawFillRequestData *fillData);// 填充用于批量传输的请求
  2. int32_t U***RawFillControlSetup(const unsigned char *setup, const struct U***ControlRequestData *requestData);
  3. int32_t U***RawFillControlRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RawFillRequestData *fillData);// 填充用于控制传输的请求
  4. int32_t U***RawFillInterruptRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RawFillRequestData *fillData);// 填充用于中断传输的请求
  5. int32_t U***RawFillIsoRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RawFillRequestData *fillData);// 填充用于同步传输的请求
复制代码

(6) 提交IO Request对象，可以选择同步或异步两种模式，分别使用如下接口：
  1. int32_t U***RawSendControlRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***ControlRequestData *requestData);//发送同步USB控制传输请求
  2. int32_t U***RawSendBulkRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RequestData *requestData);//发送同步USB批量传输请求
  3. int32_t U***RawSendInterruptRequest(const struct U***RawRequest *request, const U***RawHandle *devHandle, const struct U***RequestData *requestData);//发送同步执行USB中断传输请求
  4. int32_t U***RawSubmitRequest(const struct U***RawRequest *request);//提交异步IO请求
复制代码

感兴趣的小伙伴可点击下方链接查看完整的USB Host开发代码：

2）USB Device的开发

USB Device（设备端驱动）主要实现设备管理、配置管理、IO管理、数据通信等。USB Deivce DDK给开发者提供了设备创建、获取接口、接收Event事件、收发数据等驱动能力接口，如图5所示：

图5 USB Device DDK开放的API

下面，我们将根据USB Deivce DDK提供的驱动能力接口来开发设备端驱动。

1. 构造描述符

首先，需构造描述符来说明设备的总体信息。开发者可以通过设备功能代码及设备私有数据HCS两种途径进行配置，下面将分别介绍。

(1) 在设备功能代码中配置描述符，配置代码如下：
  1. static struct U***FnFunction g_acmFunction = {//功能描述符
  2.     .enable         = true,
  3.     .funcName       = "f_generic.a",
  4.     .strings        = g_acmStrings,
  5.     .fsDescriptors  = g_acmFsFunction,
  6.     .hsDescriptors  = g_acmHsFunction,
  7.     .ssDescriptors  = g_acmSsFunction,
  8. .sspDescriptors = NULL,
  9. };
  10. struct U***FnFunction *g_functions[] = {
  11. #ifdef CDC_ECM
  12.     &g_ecmFunction,
  13. #endif
  14. #ifdef CDC_ACM
  15.     &g_acmFunction,
  16. #endif
  17. NULL
  18. };
  19. static struct U***FnConfiguration g_masterConfig = {//配置描述符
  20.     .configurationValue = 1,
  21.     .iConfiguration     = USB_FUNC_CONFIG_IDX,
  22.     .attributes         = USB_CFG_BUS_POWERED,
  23.     .maxPower           = POWER,
  24.     .functions          = g_functions,
  25. };
  26. static struct U***FnConfiguration *g_configs[] = {
  27.     &g_masterConfig,
  28.     NULL,
  29. };
  30. static struct U***DeviceDescriptor g_cdcMasterDeviceDesc = {//设备描述符
  31.     .bLength            = sizeof(g_cdcMasterDeviceDesc),
  32.     .bDescriptorType    = USB_DDK_DT_DEVICE,
  33.     .bcdUSB             = CpuToLe16(BCD_USB),
  34.     .bDeviceClass       = 0,
  35.     .bDeviceSubClass    = 0,
  36.     .bDeviceProtocol    = 0,
  37.     .bMaxPacketSize0    = USB_MAX_PACKET_SIZE,
  38.     .idVendor           = CpuToLe16(DEVICE_VENDOR_ID),
  39.     .idProduct          = CpuToLe16(DEVICE_PRODUCT_ID),
  40.     .bcdDevice          = CpuToLe16(DEVICE_VERSION),
  41.     .iManufacturer      = USB_FUNC_MANUFACTURER_IDX,
  42.     .iProduct           = USB_FUNC_PRODUCT_IDX,
  43.     .iSerialNumber      = USB_FUNC_SERIAL_IDX,
  44.     .bNumConfigurations = 1,
  45. };
  46. static struct U***FnDeviceDesc g_masterFuncDevice = {//描述符入口
  47.     .deviceDesc    = &g_cdcMasterDeviceDesc,
  48.     .deviceStrings = g_devStrings,
  49.     .configs       = g_configs,
  50. };
复制代码

(2) 在设备私有数据HCS中配置，配置代码如下：
  1. root {
  2.     module = "master";
  3. master_config {
  4.         match_attr         = "u***fn_master_driver";//该字段与device中deviceMatchAttr
  5.                                                              保持一致，否则无法找到的这个节点的信息。
  6.     use_hcs            = 1;                         //用户可以用该值决定是否使用hcs配置信息
  7.     udc_name           = "100e0000.hidwc3_0";   //UDC的名字
  8.         u***_dev_desc       = "U***DeviceDescriptor";//设备描述符的节点U***DeviceDescriptor
  9.         u***_dev_string     = "U***DeviceStrings";   //设备字符串的节点为U***DeviceStrings
  10.         u***_configuration = "U***Configs";           //配置描述符的节点为U***Configs
  11.         ...
  12.    }
  13. }
复制代码

设备描述符的节点为U***DeviceDescriptor，配置如下：
  1. U***DeviceDescriptor {
  2.             bLength            = 18;
  3.             bDescriptorType  = 0x01;
  4.             bcdUSB             = 0x0200;
  5.             bDeviceClass      = 0;
  6.             bDeviceSubClass  = 0;
  7.             bDeviceProtocol  = 0;
  8.             bMaxPacketSize0  = 0x40;
  9.             idVendor           = 0x0525;
  10.             idProduct          = 0xA4A7;
  11.             bcdDevice          = 0x0100;
  12.             manufacturer       = 0;
  13.             product             = 1;
  14.             serialnumber       = 2;
  15.             numConfigurations = 1;
  16. }
复制代码

2. 创建设备

描述符构造完成后，使用U***FnDeviceCreate函数创建一个USB设备，并传入UDC控制器名和U***FnDescriptorData结构体。实现代码如下：
  1. if (useHcs == 0) {//使用代码编写的描述符
  2.         descData.type        = USBFN_DESC_DATA_TYPE_DESC;
  3.         descData.descriptor = &g_acmFuncDevice;
  4.     } else {             //使用hcs编写的描述符
  5.         descData.type         = USBFN_DESC_DATA_TYPE_PROP;
  6.         descData.property    = acm->device->property;
  7. }
  8.    //创建设备
  9.     fnDev = (struct U***FnDevice *) U***FnCreateDevice(acm->udcName, &descData);
复制代码

3.获取接口

设备创建后，使用U***FnDeviceGetInterface函数获取U***Interface接口对象，并通过U***FnGetInterfacePipeInfo函数获取USB管道信息，实现代码如下：
  1. //获取接口
  2. fnIface = (struct U***FnInterface *)U***FnGetInterface(fnDev, i);
  3. //获取Pipe信息
  4. U***FnGetInterfacePipeInfo(fnIface, i, &pipeInfo);
  5. //获取Handle
  6. handle = U***FnOpenInterface(fnIface);
  7. //获取控制（EP0）Request
  8. req = U***FnAllocCtrlRequest(acm->ctrlIface.handle,
  9.             sizeof(struct U***CdcLineCoding) + sizeof(struct U***CdcLineCoding));
  10. //获取Request
  11. req = U***FnAllocCtrlRequest(acm->ctrlIface.handle,
  12.             sizeof(struct U***CdcLineCoding) + sizeof(struct U***CdcLineCoding));
复制代码

4. 接收Event事件

通过U***FnStartRecvInterfaceEvent函数接收Event事件，并通过U***FnEventCallback回调函数对Event事件做出响应，实现代码如下：
  1. //开始接收Event事件
  2. ret = U***FnStartRecvInterfaceEvent(acm->ctrlIface.fn, 0xff, U***AcmEventCallback, acm);
  3. //Event处理回调函数
  4. static void U***AcmEventCallback(struct U***FnEvent *event)
  5. {
  6. struct U***AcmDevice *acm = NULL;
  9.     if (event == NULL || event->context == NULL) {
  10.         HDF_LOGE("%s: event is null", __func__);
  11.         return;
  12.     }
  15.     acm = (struct U***AcmDevice *)event->context;
  16.     switch (event->type) {
  17.         case USBFN_STATE_BIND:
  18.             HDF_LOGI("%s: receive bind event", __func__);
  19.             break;
  20.         case USBFN_STATE_UNBIND:
  21.             HDF_LOGI("%s: receive unbind event", __func__);
  22.             break;
  23.         case USBFN_STATE_ENABLE:
  24.             HDF_LOGI("%s: receive enable event", __func__);
  25.             AcmEnable(acm);
  26.             break;
  27.         case USBFN_STATE_DISABLE:
  28.             HDF_LOGI("%s: receive disable event", __func__);
  29.             AcmDisable(acm);
  30.             acm->enableEvtCnt = 0;
  31.             break;
  32.         case USBFN_STATE_SETUP:
  33.             HDF_LOGI("%s: receive setup event", __func__);
  34.             if (event->setup != NULL) {
  35.                 AcmSetup(acm, event->setup);
  36.             }
  37.             break;
  38.         case USBFN_STATE_SUSPEND:
  39.             HDF_LOGI("%s: receive suspend event", __func__);
  40.             AcmSuspend(acm);
  41.             break;
  42.         case USBFN_STATE_RESUME:
  43.             HDF_LOGI("%s: receive resume event", __func__);
  44.             AcmResume(acm);
  45.             break;
  46.         default:
  47.             break;
  48.     }
  49. }
复制代码

5. 收发数据

可以选择同步异步发送模式，实现代码如下：
  1. notify = (struct U***CdcNotification *)req->buf;
  2.     ...
  3.     if (memcpy_s((void *)(notify + 1), length, data, length)  != EOK) {
  4.         return HDF_FAILURE;
  5.     }
  6. ret = U***FnSubmitRequestAsync(req);//异步发送
复制代码

感兴趣的小伙伴可点击下方链接查看完整的设备测开发代码。


以上就是本期全部内容，通过本文的介绍相信你已经对USB DDK有了深刻的认识，期待广大的开发者加入我们，一起丰富基于USB DDK的第三方驱动。

举报

回帖

声明：本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人，不代表电子发烧友网立场。文章及其配图仅供工程师学习之用，如有内容图片侵权或者其他问题，请联系本站作侵删。 侵权投诉
链接复制成功，分享给好友