1# USB DDK开发指导
2
3## 场景介绍
4
5USB DDK（USB Driver Develop Kit）是为开发者提供的USB驱动程序开发套件，支持开发者基于用户态，在应用层开发USB设备驱动。提供了一系列主机侧访问设备的接口，包括主机侧打开和关闭接口、管道同步异步读写通信、控制传输、中断传输等。
6
7## 约束与限制
8
9* USB DDK开放API支持USB接口非标外设扩展驱动开发场景。
10
11* USB DDK开放API使用范围内仅允许DriverExtensionAbilit生命周期内使用。
12
13* 使用USB DDK开放API需要在module.json5中声明匹配的ACL权限，例如ohos.permission.ACCESS_DDK_USB。
14
15## 接口说明
16
17| 名称 | 描述 |
18| -------- | -------- |
19| OH_Usb_Init(void) | 初始化DDK。 |
20| OH_Usb_Release(void) | 释放DDK。 |
21| OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc) | 获取设备描述符。 |
22| OH_Usb_GetConfigDescriptor(uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) | 获取配置描述符。请在描述符使用完后使用OH_Usb_FreeConfigDescriptor()释放描述符，否则会造成内存泄露。 |
23| OH_Usb_FreeConfigDescriptor(const struct UsbDdkConfigDescriptor *const config) | 释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 |
24| OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) | 声明接口。 |
25| OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex) | 激活接口的备用设置。 |
26| OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t \*settingIndex) | 获取接口当前激活的备用设置。 |
27| OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup \*setup, uint32_t timeout, uint8_t \*data, uint32_t \*dataLen) | 发送控制读请求，该接口为同步接口。 |
28| OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup \*setup, uint32_t, const uint8_t \*data, uint32_t dataLen) | 发送控制写请求，该接口为同步接口。 |
29| OH_Usb_ReleaseInterface(uint64_t interfaceHandle) | 释放接口。 |
30| OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) | 发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 |
31| OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) | 创建缓冲区。请在缓冲区使用完后，调用OH_Usb_DestroyDeviceMemMap()销毁缓冲区，否则会造成资源泄露。 |
32| OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap) | 销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 |
33
34详细的接口说明请参考[USB DDK](../reference/apis-driverdevelopment-kit/_usb_ddk.md)。
35
36## 开发步骤
37
38以下步骤描述了如何使用 **USB DDK**开发USB驱动：
39
40**添加动态链接库**
41
42CMakeLists.txt中添加以下lib。
43```txt
44libusb_ndk.z.so
45```
46
47**头文件**
48```c++
49#include <usb/usb_ddk_api.h>
50#include <usb/usb_ddk_types.h>
51```
52
531. 获取设备描述符。
54
55    使用 **usb_ddk_api.h** 的 **OH_Usb_Init** 接口初始化DDK，并使用 **OH_Usb_GetDeviceDescriptor**获取到设备描述符。
56
57    ```c++
58    // 初始化USB DDK
59    OH_Usb_Init();
60    struct UsbDeviceDescriptor devDesc;
61    uint64_t deviceId = 0;
62    // 获取设备描述符
63    OH_Usb_GetDeviceDescriptor(deviceId, &devDesc);
64    ```
65
662. 获取配置描述符及声明接口。
67
68    使用 **usb_ddk_api.h** 的 **OH_Usb_GetConfigDescriptor** 接口获取配置描述符 **config**，并使用 OH_Usb_ClaimInterface 声明"认领"接口。。
69
70    ```c++
71    struct UsbDdkConfigDescriptor *config = nullptr;
72    // 获取配置描述符
73    OH_Usb_GetConfigDescriptor(deviceId, 1, &config);
74    // 根据配置描述符,找到所需要通信的interfaceIndex
75    uint8_t interfaceIndex = 0;
76    // 声明接口
77    uint64_t interfaceHandle = 0;
78    OH_Usb_ClaimInterface(deviceId, interfaceIndex, &interfaceHandle);
79    // 释放配置描述符
80    OH_Usb_FreeConfigDescriptor(config);
81    ```
823. 获取当前激活接口的备用设置及激活备用设置。
83
84    使用 **usb_ddk_api.h** 的 **OH_Usb_GetCurrentInterfaceSetting** 获取备用设置，并使用 **OH_Usb_SelectInterfaceSetting** 激活备用设置
85
86    ```c++
87    uint8_t settingIndex = 0;
88    // 接口获取备用设置
89    OH_Usb_GetCurrentInterfaceSetting(interfaceHandle, &settingIndex);
90
91    // 激活备用设置
92    OH_Usb_SelectInterfaceSetting(interfaceHandle, &settingIndex);
93    ```
944. 发送控制读请求、发送控制写请求。
95
96    使用 **usb_ddk_api.h** 的**OH_Usb_SendControlReadRequest**发送控制读请求，或者使用**OH_Usb_SendControlWriteRequest**发送控制写请求。
97
98    ```c++
99        // 超时时间，设置为1s;
100    uint32_t timeout = 1000;
101
102    struct UsbControlRequestSetup setupRead;
103    setupRead.bmRequestType	= 0x80;
104    setupRead.bRequest = 0x08;
105    setupRead.wValue = 0;
106    setupRead.wIndex = 0;
107    setupRead.wLength = 0x01;
108    uint8_t dataRead[256] = {0};
109    uint32_t dataReadLen = 256;
110    // 发送控制读请求
111    OH_Usb_SendControlReadRequest(interfaceHandle, &setupRead, timeout, dataRead, &dataReadLen);
112
113    struct UsbControlRequestSetup setupWrite;
114    setupWrite.bmRequestType = 0;
115    setupWrite.bRequest = 0x09;
116    setupWrite.wValue = 1;
117    setupWrite.wIndex = 0;
118    setupWrite.wLength = 0;
119    uint8_t dataWrite[256] = {0};
120    uint32_t dataWriteLen = 256;
121    // 发送控制写请求
122    OH_Usb_SendControlWriteRequest(interfaceHandle, &setupWrite, timeout, dataWrite, &dataWriteLen);
123    ```
124
1255. 创建内存映射缓冲区及发送请求。
126
127    使用 **usb_ddk_api.h** 的**OH_Usb_CreateDeviceMemMap**接口创建内存映射缓冲区**devMmap**，并使用**OH_Usb_SendPipeRequest**发送请求。
128
129    ```c++
130    struct UsbDeviceMemMap *devMmap = nullptr;
131    // 创建用于存放数据的缓冲区
132    size_t bufferLen = 10;
133    OH_Usb_CreateDeviceMemMap(deviceId, bufferLen, &devMmap);
134    struct UsbRequestPipe pipe;
135    pipe.interfaceHandle = interfaceHandle;
136    // 根据配置描述符找到所要通信的端点
137    pipe.endpoint = 128;
138    pipe.timeout = UINT32_MAX;
139    // 发送请求
140    OH_Usb_SendPipeRequest(&pipe, devMmap);
141    ```
142
1436. 释放资源。
144
145    在所有请求处理完毕，程序退出前，使用 **usb_ddk_api.h** 的 **OH_Usb_DestroyDeviceMemMap** 接口销毁缓冲区。使用**OH_Usb_ReleaseInterface**释放接口。使用**OH_Usb_Release**释放USB DDK。
146
147    ```c++
148    // 销毁缓冲区
149    OH_Usb_DestroyDeviceMemMap(devMmap);
150    // 释放接口
151    OH_Usb_ReleaseInterface(interfaceHandle);
152    // 释放USB DDK
153    OH_Usb_Release();
154    ```
155