HDF（Hardware Driver Foundation）驅(qū)動(dòng)框架是HarmonyOS硬件生態(tài)開(kāi)放的基礎(chǔ)，為開(kāi)發(fā)者提供了驅(qū)動(dòng)加載、驅(qū)動(dòng)服務(wù)管理和驅(qū)動(dòng)消息機(jī)制等驅(qū)動(dòng)能力，讓開(kāi)發(fā)者能精準(zhǔn)且高效的開(kāi)發(fā)驅(qū)動(dòng)程序。本期，我們將為大家?guī)?lái)HDF驅(qū)動(dòng)框架中USB DDK的解析與指導(dǎo)。

USB DDK（USB DriverDevelop Kit）是HDF驅(qū)動(dòng)框架為開(kāi)發(fā)者提供的USB驅(qū)動(dòng)程序開(kāi)發(fā)套件，包括USB Host DDK及USB Device DDK兩部分，支持基于用戶(hù)態(tài)開(kāi)發(fā)USB設(shè)備驅(qū)動(dòng)的同時(shí)，還提供了豐富的USB驅(qū)動(dòng)開(kāi)發(fā)能力，讓廣大開(kāi)發(fā)者能精準(zhǔn)且高效的開(kāi)發(fā)USB驅(qū)動(dòng)程序。下面，我們將一一道來(lái)。

1USB Host DDK

USB Host DDK給開(kāi)發(fā)者提供了主機(jī)端USB驅(qū)動(dòng)開(kāi)發(fā)能力，按照功能分類(lèi)三大類(lèi),分別是DDK初始化類(lèi)、interface對(duì)象操作類(lèi)及request對(duì)象操作類(lèi)。并為開(kāi)發(fā)者提供了普通模式和專(zhuān)家模式兩種開(kāi)發(fā)模式。普通模式下，開(kāi)發(fā)者可通過(guò)USBDDK API直接完成相關(guān)USB數(shù)據(jù)讀寫(xiě)操作，不需要過(guò)多關(guān)注底層傳輸細(xì)節(jié)。專(zhuān)家模式下，開(kāi)發(fā)者通過(guò)USB RAW API直接訪(fǎng)問(wèn)OS平臺(tái)USB通道的接口，自定義實(shí)現(xiàn)更加復(fù)雜的功能。目的是給驅(qū)動(dòng)層留有更靈活，更強(qiáng)大的擴(kuò)展方案，同時(shí)也能夠兼容現(xiàn)有驅(qū)動(dòng)，便于移植。USBHost DDK架構(gòu)如圖1所示：

2USB Device DDK

USB Device DDK給開(kāi)發(fā)者提供了設(shè)備端USB驅(qū)動(dòng)開(kāi)發(fā)能力。例如，USB端口動(dòng)態(tài)注冊(cè)和去注冊(cè)能力，開(kāi)發(fā)者可以基于能力實(shí)現(xiàn)USB端口的動(dòng)態(tài)添加和組合；動(dòng)態(tài)實(shí)例化能力，支持根據(jù)動(dòng)態(tài)下發(fā)設(shè)備、配置、接口及端點(diǎn)描述符創(chuàng)建設(shè)備實(shí)例及傳輸通道；用戶(hù)態(tài)的數(shù)據(jù)發(fā)送及接收能力，支持用戶(hù)態(tài)下發(fā)送及接收數(shù)據(jù)；復(fù)合設(shè)備能力，支持一個(gè)物理設(shè)備上多個(gè)邏輯設(shè)備，實(shí)現(xiàn)多個(gè)邏輯設(shè)備間隔離，并支持不同邏輯設(shè)備同時(shí)被不同的應(yīng)用進(jìn)程訪(fǎng)問(wèn)。USB Device DDK架構(gòu)如圖2所示：

1USB Host的開(kāi)發(fā)

USB Host（主機(jī)端驅(qū)動(dòng)）主要完成協(xié)議封裝、設(shè)備管理、驅(qū)動(dòng)安裝與卸載等。通過(guò)上文的介紹，開(kāi)發(fā)者可通過(guò)USB DDK API和USB RAW API來(lái)實(shí)現(xiàn)主機(jī)端驅(qū)動(dòng)。

1. USB DDK API的使用

圖3 USB DDK API部分接口

使用步驟如下：

(1) 配置驅(qū)動(dòng)匹配表，完成主機(jī)端驅(qū)動(dòng)總體信息的配置，具體如下：

struct UsbPnpMatchIdTable {//驅(qū)動(dòng)模塊名，該字段的值必須和驅(qū)動(dòng)入口結(jié)構(gòu)的moduleName一致const char *moduleName;//驅(qū)動(dòng)對(duì)外發(fā)布服務(wù)的名稱(chēng)，必須唯一const char *serviceName;//驅(qū)動(dòng)私有數(shù)據(jù)匹配關(guān)鍵字const char *deviceMatchAttr;//從該字段開(kāi)始（包含該字段）之后數(shù)據(jù)長(zhǎng)度，以byte為單位uint8_t length;//USB驅(qū)動(dòng)匹配規(guī)則uint16_t matchFlag;//廠(chǎng)商編號(hào)uint16_t vendorId;//產(chǎn)品編號(hào)uint16_t productId;//設(shè)備出廠(chǎng)編號(hào)，低16位uint16_t bcdDeviceLow;//設(shè)備出廠(chǎng)編號(hào)，高16位uint16_t bcdDeviceHigh;  //USB分配的設(shè)備類(lèi)代碼uint8_t deviceClass;//USB分配的子類(lèi)代碼uint8_t deviceSubClass;//USB分配的設(shè)備協(xié)議代碼uint8_t deviceProtocol;//接口類(lèi)型，根據(jù)實(shí)際需要可填寫(xiě)多個(gè)uint8_t interfaceClass[USB_PNP_INFO_MAX_INTERFACES];//接口子類(lèi)型，根據(jù)實(shí)際需要可填寫(xiě)多個(gè)uint8_t interfaceSubClass[USB_PNP_INFO_MAX_INTERFACES];//接口所遵循的協(xié)議，根據(jù)實(shí)際需要可填寫(xiě)多個(gè)uint8_t interfaceProtocol[USB_PNP_INFO_MAX_INTERFACES];//接口的編號(hào)，根據(jù)實(shí)際需要可填寫(xiě)多個(gè)uint8_t interfaceNumber[USB_PNP_INFO_MAX_INTERFACES];};

enum {    USB_PNP_NOTIFY_MATCH_VENDOR = 0x0001,    USB_PNP_NOTIFY_MATCH_PRODUCT = 0x0002,    USB_PNP_NOTIFY_MATCH_DEV_LOW = 0x0004,    USB_PNP_NOTIFY_MATCH_DEV_HIGH = 0x0008,    USB_PNP_NOTIFY_MATCH_DEV_CLASS = 0x0010,    USB_PNP_NOTIFY_MATCH_DEV_SUBCLASS = 0x0020,    USB_PNP_NOTIFY_MATCH_DEV_PROTOCOL = 0x0040,    USB_PNP_NOTIFY_MATCH_INT_CLASS = 0x0080,    USB_PNP_NOTIFY_MATCH_INT_SUBCLASS = 0x0100,    USB_PNP_NOTIFY_MATCH_INT_PROTOCOL = 0x0200,    USB_PNP_NOTIFY_MATCH_INT_NUMBER = 0x0400,};

int32_t UsbInitHostSdk(struct UsbSession **session)

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

UsbInterfaceHandle *UsbOpenInterface(const struct UsbInterface *interfaceObj);

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

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

int32_t UsbFillRequest(const struct UsbRequest *request, const UsbInterfaceHandle *interfaceHandle, const struct UsbRequestParams *params);

int32_t UsbSubmitRequestSync(const struct UsbRequest *request);//發(fā)送同步IO請(qǐng)求int32_t UsbSubmitRequestAsync(const struct UsbRequest *request);//發(fā)送異步IO請(qǐng)求

USB RAW API主要實(shí)現(xiàn)USB更加復(fù)雜的功能，如獲取描述符信息、獲取設(shè)備指針、復(fù)位設(shè)備、提交傳輸請(qǐng)求等，如圖4所示，是USB RAW API提供的部分接口。

(1) 同USB DDK API的步驟1一樣，需先進(jìn)行驅(qū)動(dòng)匹配表配置。

int32_t UsbRawInit(struct UsbSession **session);

UsbRawHandle *UsbRawOpenDevice(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr);

int32_t UsbRawGetConfigDescriptor(const UsbRawDevice *rawDev, uint8_t configIndex, struct UsbRawConfigDescriptor **config);

int32_t UsbRawFillBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);// 填充用于批量傳輸?shù)恼?qǐng)求int32_t UsbRawFillControlSetup(const unsigned char *setup, const struct UsbControlRequestData *requestData);int32_t UsbRawFillControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);// 填充用于控制傳輸?shù)恼?qǐng)求int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);// 填充用于中斷傳輸?shù)恼?qǐng)求int32_t UsbRawFillIsoRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);// 填充用于同步傳輸?shù)恼?qǐng)求

int32_t UsbRawSendControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbControlRequestData *requestData);//發(fā)送同步USB控制傳輸請(qǐng)求int32_t UsbRawSendBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);//發(fā)送同步USB批量傳輸請(qǐng)求int32_t UsbRawSendInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);//發(fā)送同步執(zhí)行USB中斷傳輸請(qǐng)求int32_t UsbRawSubmitRequest(const struct UsbRawRequest *request);//提交異步IO請(qǐng)求

2USB Device的開(kāi)發(fā)

USB Device（設(shè)備端驅(qū)動(dòng)）主要實(shí)現(xiàn)設(shè)備管理、配置管理、IO管理、數(shù)據(jù)通信等。USB Deivce DDK給開(kāi)發(fā)者提供了設(shè)備創(chuàng)建、獲取接口、接收Event事件、收發(fā)數(shù)據(jù)等驅(qū)動(dòng)能力接口，如圖5所示：

首先，需構(gòu)造描述符來(lái)說(shuō)明設(shè)備的總體信息。開(kāi)發(fā)者可以通過(guò)設(shè)備功能代碼及設(shè)備私有數(shù)據(jù)HCS兩種途徑進(jìn)行配置，下面將分別介紹。

static struct UsbFnFunction g_acmFunction = {//功能描述符    .enable         = true,    .funcName       = "f_generic.a",    .strings        = g_acmStrings,    .fsDescriptors  = g_acmFsFunction,    .hsDescriptors  = g_acmHsFunction,    .ssDescriptors  = g_acmSsFunction,.sspDescriptors = NULL,};struct UsbFnFunction *g_functions[] = {#ifdef CDC_ECM    &g_ecmFunction,#endif#ifdef CDC_ACM    &g_acmFunction,#endifNULL};static struct UsbFnConfiguration g_masterConfig = {//配置描述符    .configurationValue = 1,    .iConfiguration     = USB_FUNC_CONFIG_IDX,    .attributes         = USB_CFG_BUS_POWERED,    .maxPower           = POWER,    .functions          = g_functions,};static struct UsbFnConfiguration *g_configs[] = {    &g_masterConfig,    NULL,};static struct UsbDeviceDescriptor g_cdcMasterDeviceDesc = {//設(shè)備描述符    .bLength            = sizeof(g_cdcMasterDeviceDesc),    .bDescriptorType    = USB_DDK_DT_DEVICE,    .bcdUSB             = CpuToLe16(BCD_USB),    .bDeviceClass       = 0,    .bDeviceSubClass    = 0,    .bDeviceProtocol    = 0,    .bMaxPacketSize0    = USB_MAX_PACKET_SIZE,    .idVendor           = CpuToLe16(DEVICE_VENDOR_ID),    .idProduct          = CpuToLe16(DEVICE_PRODUCT_ID),    .bcdDevice          = CpuToLe16(DEVICE_VERSION),    .iManufacturer      = USB_FUNC_MANUFACTURER_IDX,    .iProduct           = USB_FUNC_PRODUCT_IDX,    .iSerialNumber      = USB_FUNC_SERIAL_IDX,    .bNumConfigurations = 1,};static struct UsbFnDeviceDesc g_masterFuncDevice = {//描述符入口    .deviceDesc    = &g_cdcMasterDeviceDesc,    .deviceStrings = g_devStrings,    .configs       = g_configs,};

root {    module = "master";master_config {        match_attr         = "usbfn_master_driver";//該字段與device中deviceMatchAttr                                                             保持一致，否則無(wú)法找到的這個(gè)節(jié)點(diǎn)的信息。    use_hcs            = 1;                         //用戶(hù)可以用該值決定是否使用hcs配置信息    udc_name           = "100e0000.hidwc3_0";   //UDC的名字        usb_dev_desc       = "UsbDeviceDescriptor";//設(shè)備描述符的節(jié)點(diǎn)UsbDeviceDescriptor        usb_dev_string     = "UsbDeviceStrings";   //設(shè)備字符串的節(jié)點(diǎn)為UsbDeviceStrings        usb_configuration = "UsbConfigs";           //配置描述符的節(jié)點(diǎn)為UsbConfigs        ...   }}

UsbDeviceDescriptor {            bLength            = 18;            bDescriptorType  = 0x01;            bcdUSB             = 0x0200;            bDeviceClass      = 0;            bDeviceSubClass  = 0;            bDeviceProtocol  = 0;            bMaxPacketSize0  = 0x40;            idVendor           = 0x0525;            idProduct          = 0xA4A7;            bcdDevice          = 0x0100;            manufacturer       = 0;            product             = 1;            serialnumber       = 2;            numConfigurations = 1;  }

描述符構(gòu)造完成后，使用UsbFnDeviceCreate函數(shù)創(chuàng)建一個(gè)USB設(shè)備，并傳入U(xiǎn)DC控制器名和UsbFnDescriptorData結(jié)構(gòu)體。實(shí)現(xiàn)代碼如下：

 if (useHcs == 0) {//使用代碼編寫(xiě)的描述符        descData.type        = USBFN_DESC_DATA_TYPE_DESC;        descData.descriptor = &g_acmFuncDevice;    } else {             //使用hcs編寫(xiě)的描述符        descData.type         = USBFN_DESC_DATA_TYPE_PROP;        descData.property    = acm->device->property;}   //創(chuàng)建設(shè)備    fnDev = (struct UsbFnDevice *) UsbFnCreateDevice(acm->udcName, &descData);

設(shè)備創(chuàng)建后，使用UsbFnDeviceGetInterface函數(shù)獲取UsbInterface接口對(duì)象，并通過(guò)UsbFnGetInterfacePipeInfo函數(shù)獲取USB管道信息，實(shí)現(xiàn)代碼如下：

//獲取接口fnIface = (struct UsbFnInterface *)UsbFnGetInterface(fnDev, i);//獲取Pipe信息UsbFnGetInterfacePipeInfo(fnIface, i, &pipeInfo);//獲取Handlehandle = UsbFnOpenInterface(fnIface);//獲取控制（EP0）Requestreq = UsbFnAllocCtrlRequest(acm->ctrlIface.handle,            sizeof(struct UsbCdcLineCoding) + sizeof(struct UsbCdcLineCoding));//獲取Requestreq = UsbFnAllocCtrlRequest(acm->ctrlIface.handle,            sizeof(struct UsbCdcLineCoding) + sizeof(struct UsbCdcLineCoding));

通過(guò)UsbFnStartRecvInterfaceEvent函數(shù)接收Event事件，并通過(guò)UsbFnEventCallback回調(diào)函數(shù)對(duì)Event事件做出響應(yīng)，實(shí)現(xiàn)代碼如下：

//開(kāi)始接收Event事件ret = UsbFnStartRecvInterfaceEvent(acm->ctrlIface.fn, 0xff, UsbAcmEventCallback, acm);//Event處理回調(diào)函數(shù)static void UsbAcmEventCallback(struct UsbFnEvent *event){struct UsbAcmDevice *acm = NULL;

    if (event == NULL || event->context == NULL) {        HDF_LOGE("%s: event is null", __func__);        return;    }

    acm = (struct UsbAcmDevice *)event->context;    switch (event->type) {        case USBFN_STATE_BIND:            HDF_LOGI("%s: receive bind event", __func__);            break;        case USBFN_STATE_UNBIND:            HDF_LOGI("%s: receive unbind event", __func__);            break;        case USBFN_STATE_ENABLE:            HDF_LOGI("%s: receive enable event", __func__);            AcmEnable(acm);            break;        case USBFN_STATE_DISABLE:            HDF_LOGI("%s: receive disable event", __func__);            AcmDisable(acm);            acm->enableEvtCnt = 0;            break;        case USBFN_STATE_SETUP:            HDF_LOGI("%s: receive setup event", __func__);            if (event->setup != NULL) {                AcmSetup(acm, event->setup);            }            break;        case USBFN_STATE_SUSPEND:            HDF_LOGI("%s: receive suspend event", __func__);            AcmSuspend(acm);            break;        case USBFN_STATE_RESUME:            HDF_LOGI("%s: receive resume event", __func__);            AcmResume(acm);            break;        default:            break;    }}

可以選擇同步異步發(fā)送模式，實(shí)現(xiàn)代碼如下：

notify = (struct UsbCdcNotification *)req->buf;    ...    if (memcpy_s((void *)(notify + 1), length, data, length)  != EOK) {        return HDF_FAILURE;    }ret = UsbFnSubmitRequestAsync(req);//異步發(fā)送

以上就是本期全部?jī)?nèi)容，通過(guò)本文的介紹相信你已經(jīng)對(duì)USB DDK有了深刻的認(rèn)識(shí)，期待廣大的開(kāi)發(fā)者加入我們，一起豐富基于USB DDK的第三方驅(qū)動(dòng)。

原文標(biāo)題：USB DDK助你輕松實(shí)現(xiàn)USB驅(qū)動(dòng)開(kāi)發(fā)