# USB - [Introduction](#section11660541593) - [Directory Structure](#section161941989596) - [Available APIs](#section1551164914237) - [How to Use](#section129654513264) - [Repositories Involved](#section1371113476307) ## Introduction This repository contains the API definitions of the USB host Driver Development Kit (DDK) and USB device DDK and their implementation. - USB host DDK: provides APIs to read and write USB device data of third-party function drivers in user mode, register device insertion/removal time notifications with the kernel USB driver framework, and remove USB logical devices. **Figure 1** Logical view of the modules on the USB host ![](figures/logic-view-of-usb-host-modules.png "logic-view-of-usb-host-modules") - USB device DDK: creates and deletes USB devices, obtains notification events, enables or disables event listening, implements non-isochronous and isochronous data transfer over USB pipes, and sets custom USB attributes. **Figure 2** Logical view of the modules on the USB device ![](figures/logic-view-of-usb-device-modules.png "logic-view-of-usb-device-modules") ## Directory Structure The source code directory structure is as follows: ``` /drivers/peripheral/usb ├── ddk # DDK of the USB modules │ └── device # DDK implementation for the USB device │ └── host # DDK implementation for the USB host ├── gadget # Driver demo implementation for the USB device │ └── function # Driver demo for the USB device, including the abstract communication model (ACM) driver and Ethernet control model (ECM) driver ├── interfaces # Driver capability APIs in user mode │ └── ddk # API definitions for both the USB device and host ├── net # ECM driver demo implementation for the USB host ├── sample # Application test program implementation │ └── device # Implementation of the ACM driver read/write and speed test application for the USB device (for Linux and LiteOS) │ └── host # Implementation of the ACM driver read/write and speed test application for the USB host (for Linux and LiteOS) ├── serial # ACM driver demo implementation for the USB host ├── test # Test code │ └── unittest # Unit test code for both the USB host and device ``` ### Available APIs The USB host DDK provides driver capability APIs that can be directly called in user mode. The APIs can be classified into the DDK initialization class, interface operation class, and request operation class by function. These APIs can be used to perform DDK initialization, bind/release and open/close an interface, allocate/release a request, and implement isochronous or non-isochronous transfer. [Table 1](#table1513255710559) describes some of the USB host DDK APIs. **Table 1** USB host DDK APIs

Header File

API

Description

usb_ddk_interface.h

int32_t UsbInitHostSdk(struct UsbSession **session);

Initializes the USB host DDK.

int32_t UsbExitHostSdk(const struct UsbSession *session);

Exits the USB host DDK.

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

Claims a USB interface.

int32_t UsbReleaseInterface(const struct UsbInterface *interfaceObj);

Releases a USB interface.

int32_t UsbAddOrRemoveInterface(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr, uint8_t interfaceIndex, UsbInterfaceStatus status);

Adds or removes a USB interface.

UsbInterfaceHandle *UsbOpenInterface(const struct UsbInterface *interfaceObj);

Opens a USB interface.

int32_t UsbCloseInterface(const UsbInterfaceHandle *interfaceHandle);

Closes a USB interface.

int32_t UsbSelectInterfaceSetting(const UsbInterfaceHandle *interfaceHandle, uint8_t settingIndex, struct UsbInterface **interfaceObj);

Sets a USB interface.

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

Obtains USB pipe information.

int32_t UsbClearInterfaceHalt(const UsbInterfaceHandle *interfaceHandle, uint8_t pipeAddress);

Clears the state of the pipe with the specified index.

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

Allocates a request.

int32_t UsbFreeRequest(const struct UsbRequest *request);

Releases a request.

int32_t UsbSubmitRequestAsync(const struct UsbRequest *request);

Sends a request asynchronously.

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

Fills in a request.

int32_t UsbCancelRequest(const struct UsbRequest *request);

Cancels an asynchronous request.

int32_t UsbSubmitRequestSync(const struct UsbRequest *request);

Sends a synchronous request.

usb_raw_api.h

int32_t UsbRawInit(struct UsbSession **session);

Initializes the USB raw APIs.

int32_t UsbRawExit(const struct UsbSession *session);

Exits the USB raw APIs.

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

Opens a USB device.

int32_t UsbRawCloseDevice(const UsbRawHandle *devHandle);

Closes a USB device.

int32_t UsbRawSendControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbControlRequestData *requestData);

Performs isochronous control transfer.

int32_t UsbRawSendBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);

Performs isochronous bulk transfer.

int32_t UsbRawSendInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);

Performs isochronous interrupt transfer.

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

Obtains the configuration descriptor of a device.

void UsbRawFreeConfigDescriptor(const struct UsbRawConfigDescriptor *config);

Releases the memory space of a configuration descriptor.

int32_t UsbRawGetConfiguration(const UsbRawHandle *devHandle, int32_t *config);

Obtains the configuration in use.

int32_t UsbRawSetConfiguration(const UsbRawHandle *devHandle, int32_t config);

Sets the configuration in use.

int32_t UsbRawGetDescriptor(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawDescriptorParam *param, const unsigned char *data);

Obtains descriptor information.

UsbRawDevice *UsbRawGetDevice(const UsbRawHandle *devHandle);

Obtains the device pointer based on the device handle.

int32_t UsbRawGetDeviceDescriptor(const UsbRawDevice *rawDev, struct UsbDeviceDescriptor *desc);

Obtains the device descriptor of the specified USB device.

int32_t UsbRawClaimInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber);

Declares the interface on the specified device handle.

int32_t UsbRawReleaseInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber);

Releases the previously declared interface.

int32_t UsbRawResetDevice(const UsbRawHandle *devHandle);

Resets a device.

struct UsbRawRequest *UsbRawAllocRequest(const UsbRawHandle *devHandle, int32_t isoPackets, int32_t length);

Allocates a transfer request with the specified number of sync packet descriptors.

int32_t UsbRawFreeRequest(const struct UsbRawRequest *request);

Releases the previously allocated transfer request.

int32_t UsbRawFillBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);

Fills in the bulk transfer request.

int32_t UsbRawFillControlSetup(const unsigned char *setup, const struct UsbControlRequestData *requestData);

Fills in the control transfer setup packet.

int32_t UsbRawFillControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);

Fills in the control transfer request.

int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);

Fills in the interrupt transfer request.

int32_t UsbRawFillIsoRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);

Fills in the isochronous transfer request.

int32_t UsbRawSubmitRequest(const struct UsbRawRequest *request);

Submits a transfer request.

int32_t UsbRawCancelRequest(const struct UsbRawRequest *request);

Cancels a transfer request.

int32_t UsbRawHandleRequests(const UsbRawHandle *devHandle);

Handles a transfer request event.
The USB device DDK provides device management, I/O management, and configuration management APIs, which can be used to create and delete a device, obtain/open an interface, and perform isochronous or non-isochronous transfer. [Table 2](#table1513255710559) describes some of the USB device DDK APIs. **Table 2** USB device DDK APIs

Header File

API

Description

usbfn_device.h

const struct UsbFnDevice *UsbFnCreateDevice(const char *udcName, const struct UsbFnDescriptorData *descriptor);

Creates a USB device.

int32_t UsbFnRemoveDevice(struct UsbFnDevice *fnDevice);

Deletes a USB device.

const struct UsbFnDevice *UsbFnGetDevice(const char *udcName);

Obtains a USB device.

usbfn_interface.h

int32_t UsbFnStartRecvInterfaceEvent(struct UsbFnInterface *interface, uint32_t eventMask, UsbFnEventCallback callback, void *context);

Starts to receive events.

int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface);

Stops receiving events.

UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface);

Opens an interface.

int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle);

Closes an interface.

int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface *interface, uint8_t pipeId, struct UsbFnPipeInfo *info);

Obtains pipe information.

int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface *interface, const char *name, const char *value);

Sets custom attributes.

usbfn_request.h

struct UsbFnRequest *UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle, uint32_t len);

Allocates a control transfer request.

struct UsbFnRequest *UsbFnAllocRequest(UsbFnInterfaceHandle handle, uint8_t pipe, uint32_t len);

Allocates a data request.

int32_t UsbFnFreeRequest(struct UsbFnRequest *req);

Releases a request.

int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest *req);

Sends a request asynchronously.

int32_t UsbFnSubmitRequestSync(struct UsbFnRequest *req, uint32_t timeout);

Sends a request synchronously.

int32_t UsbFnCancelRequest(struct UsbFnRequest *req);

Cancels a request.
### How to Use The core functions of this repository are as follows: 1. USB host: provides DDK APIs and raw APIs, which are used to read and write USB device data of third-party function drivers in user mode. 2. USB device: provides APIs to customize USB devices, such as serial ports, network adapters, keyboards, and custom devices. ## Repositories Involved [Driver Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver.md) [drivers\_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README.md) [drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md) [drivers\_adapter\_khdf\_linux](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README.md) [drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral)