harmony 鸿蒙USB DDK Development

2023-10-30
浏览 (222)

USB DDK Development

When to Use

USB Driver Development Kit (USB DDK) is a tool kit that helps you develop USB device drivers for your applications based on the user mode. It provides a series of device access APIs, which implement functions such as opening and closing USB interfaces, performing non-isochronous and isochronous data transfer, and implementing control transfer and interrupt transfer over USB pipes, etc.

Available APIs

Name	Description
OH_Usb_Init(void)	Initializes the DDK.
OH_Usb_Release(void)	Releases the DDK.
OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc)	Obtains the device descriptor.
OH_Usb_GetConfigDescriptor(uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config)	Obtains the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor() to release a descriptor after use.
OH_Usb_FreeConfigDescriptor(const struct UsbDdkConfigDescriptor *const config)	Releases a configuration descriptor. To avoid memory leakage, release a descriptor after use.
OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle)	Declares a USB interface.
OH_Usb_ReleaseInterface(uint64_t interfaceHandle)	Releases a USB interface.
OH_Usb_SendPipeRequest(const struct UsbRequestPipe pipe, UsbDeviceMemMap devMmap)	Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.
OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap)	Creates a buffer. To avoid memory leakage, use OH_Usb_DestroyDeviceMemMap() to destroy a buffer after use.
OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap)	Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.

For details about the APIs, see USB DDK.

How to Develop

To develop a USB driver using the USB DDK, perform the following steps:

Adding Dynamic Link Libraries

Add the following libraries to CMakeLists.txt:

libusb_ndk.z.so

Including Header Files

#include <usb/usb_ddk_api.h>
#include <usb/usb_ddk_types.h>

Obtain the device descriptor. Initialize the DDK by calling OH_Usb_Init of usb_ddk_api.h, and obtain the device descriptor by calling OH_Usb_GetDeviceDescriptor.

// Initialize the USB DDK.
OH_Usb_Init();
struct UsbDeviceDescriptor devDesc;
uint64_t deviceId = 0;
// Obtain the device descriptor.
OH_Usb_GetDeviceDescriptor(deviceId, &devDesc);

Obtain the configuration descriptor, and declare the USB interface. Obtain the configuration descriptor config by calling OH_Usb_GetConfigDescriptor of usb_ddk_api.h, and declare the USB interface by calling OH_Usb_ClaimInterface.

struct UsbDdkConfigDescriptor *config = nullptr;
// Obtain the configuration descriptor.
OH_Usb_GetConfigDescriptor(deviceId, 1, &config);
// Obtain the index of the target USB interface based on the configuration descriptor.
uint8_t interfaceIndex = 0;
// Declare the USB interface.
uint64_t interfaceHandle = 0;
OH_Usb_ClaimInterface(deviceId, interfaceIndex, &interfaceHandle);
// Release the configuration descriptor.
OH_Usb_FreeConfigDescriptor(config);

Create a device memory map, and send a request. Create the device memory map devMmap by calling OH_Usb_CreateDeviceMemMap of usb_ddk_api.h, and send a request by calling OH_Usb_SendPipeRequest.

struct UsbDeviceMemMap *devMmap = nullptr;
// Create a buffer for storing data.
size_t bufferLen = 10;
OH_Usb_CreateDeviceMemMap(deviceId, bufferLen, &devMmap);
struct UsbRequestPipe pipe;
pipe.interfaceHandle = interfaceHandle;
// Obtain the target endpoint based on the configuration descriptor.
pipe.endpoint = 128;
pipe.timeout = UINT32_MAX;
// Send a request.
OH_Usb_SendPipeRequest(&pipe, devMmap);

Release resources. After all requests are processed and before the application exits, destroy the buffer by calling OH_Usb_DestroyDeviceMemMap of usb_ddk_api.h to release resources. Release the USB interface by calling OH_Usb_ReleaseInterface. Release the USB DDK by calling OH_Usb_Release.
```
// Destroy the buffer.
OH_Usb_DestroyDeviceMemMap(devMmap);
// Release the USB interface.
OH_Usb_ReleaseInterface(interfaceHandle);
// Release the USB DDK.
OH_Usb_Release();
```