update

Signed-off-by: N 葛亚芳 <geyafang@huawei.com>

update
Signed-off-by: N 葛亚芳 <geyafang@huawei.com>
4062ea51 · 葛亚芳 · Gitee · dcf804ae · 4062ea51
隐藏空白更改
内联并排

Showing with 472 addition and 0 deletion

zh-cn/application-dev/reference/native-apis/_usb_ddk.md zh-cn/application-dev/reference/native-apis/_usb_ddk.md +472 -0

未找到文件。
--- a/zh-cn/application-dev/reference/native-apis/_usb_ddk.md
+++ b/zh-cn/application-dev/reference/native-apis/_usb_ddk.md
+# UsbDdk
+
+
+## 概述
+
+提供USB DDK接口，包括主机侧打开和关闭接口、管道同步异步读写通信、控制传输、中断传输等。
+
+\@syscap SystemCapability.Driver.USB.Extension
+
+**起始版本：**
+
+10
+
+
+## 汇总
+
+
+### 文件
+
+| 名称 | 描述 |
+| -------- | -------- |
+| [usb_ddk_api.h](usb__ddk__api_8h.md) | 声明用于主机侧访问设备的USB&nbsp;DDK接口。<br/>引用文件：&lt;usb/usb_ddk_api.h&gt; |
+| [usb_ddk_types.h](usb__ddk__types_8h.md) | 提供USB&nbsp;DDK中的枚举变量、结构体定义与宏定义。<br/>引用文件：&lt;usb/usb_ddk_types.h&gt; |
+
+
+### 结构体
+
+| 名称 | 描述 |
+| -------- | -------- |
+| [UsbControlRequestSetup](_usb_control_request_setup.md) | 控制传输setup包，对应USB协议中的Setup&nbsp;Data。 |
+| [UsbDeviceDescriptor](_usb_device_descriptor.md) | 标准设备描述符，对应USB协议中Standard&nbsp;Device&nbsp;Descriptor。 |
+| [UsbConfigDescriptor](_usb_config_descriptor.md) | 标准配置描述符，对应USB协议中Standard&nbsp;Configuration&nbsp;Descriptor。 |
+| [UsbInterfaceDescriptor](_usb_interface_descriptor.md) | 标准接口描述符，对应USB协议中Standard&nbsp;Interface&nbsp;Descriptor。 |
+| [UsbEndpointDescriptor](_usb_endpoint_descriptor.md) | 标准端点描述符，对应USB协议中Standard&nbsp;Endpoint&nbsp;Descriptor。 |
+| [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) | 端点描述符。 |
+| [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) | 接口描述符。 |
+| [UsbDdkInterface](_usb_ddk_interface.md) | USB接口，是特定接口下备用设置的集合。 |
+| [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) | 配置描述符。 |
+| [UsbRequestPipe](_usb_request_pipe.md) | 请求管道。 |
+| [UsbDeviceMemMap](_usb_device_mem_map.md) | 设备内存映射，通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。 |
+
+
+### 类型定义
+
+| 名称 | 描述 |
+| -------- | -------- |
+| [UsbDdkEndpointDescriptor](#usbddkendpointdescriptor) | 端点描述符。 |
+| [UsbDdkInterfaceDescriptor](#usbddkinterfacedescriptor) | 接口描述符。 |
+| [UsbDdkInterface](#usbddkinterface) | USB接口，是特定接口下备用设置的集合。 |
+| [UsbDdkConfigDescriptor](#usbddkconfigdescriptor) | 配置描述符。 |
+| [UsbDeviceMemMap](#usbdevicememmap) | 设备内存映射，通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。 |
+
+
+### 枚举
+
+| 名称 | 描述 |
+| -------- | -------- |
+| [UsbDdkErrCode](#usbddkerrcode)&nbsp;{<br/>USB_DDK_SUCCESS&nbsp;=&nbsp;0,&nbsp;USB_DDK_FAILED&nbsp;=&nbsp;-1,&nbsp;USB_DDK_INVALID_PARAMETER&nbsp;=&nbsp;-2,&nbsp;USB_DDK_MEMORY_ERROR&nbsp;=&nbsp;-3,<br/>USB_DDK_INVALID_OPERATION&nbsp;=&nbsp;-4,&nbsp;USB_DDK_NULL_PTR&nbsp;=&nbsp;-5,&nbsp;USB_DDK_DEVICE_BUSY&nbsp;=&nbsp;-6,&nbsp;USB_DDK_TIMEOUT&nbsp;=&nbsp;-7<br/>} | USB&nbsp;DDK&nbsp;错误码定义。 |
+
+
+### 函数
+
+| 名称 | 描述 |
+| -------- | -------- |
+| [OH_Usb_Init](#oh_usb_init)&nbsp;(void) | 初始化DDK。 |
+| [OH_Usb_Release](#oh_usb_release)&nbsp;(void) | 释放DDK。 |
+| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor)&nbsp;(uint64_t&nbsp;deviceId,&nbsp;struct&nbsp;[UsbDeviceDescriptor](_usb_device_descriptor.md)&nbsp;\*desc) | 获取设备描述符。 |
+| [OH_Usb_GetConfigDescriptor](#oh_usb_getconfigdescriptor)&nbsp;(uint64_t&nbsp;deviceId,&nbsp;uint8_t&nbsp;configIndex,&nbsp;struct&nbsp;[UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md)&nbsp;\*\*const&nbsp;config) | 获取配置描述符。请在描述符使用完后使用[OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor)释放描述符，否则会造成内存泄露。 |
+| [OH_Usb_FreeConfigDescriptor](#oh_usb_freeconfigdescriptor)&nbsp;(const&nbsp;struct&nbsp;[UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md)&nbsp;\*const&nbsp;config) | 释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 |
+| [OH_Usb_ClaimInterface](#oh_usb_claiminterface)&nbsp;(uint64_t&nbsp;deviceId,&nbsp;uint8_t&nbsp;interfaceIndex,&nbsp;uint64_t&nbsp;\*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 声明接口。 |
+| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface)&nbsp;(uint64_t&nbsp;[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 释放接口。 |
+| [OH_Usb_SelectInterfaceSetting](#oh_usb_selectinterfacesetting)&nbsp;(uint64_t&nbsp;[interfaceHandle](usb__ddk__types_8h.md#interfacehandle),&nbsp;uint8_t&nbsp;settingIndex) | 激活接口的备用设置。 |
+| [OH_Usb_GetCurrentInterfaceSetting](#oh_usb_getcurrentinterfacesetting)&nbsp;(uint64_t&nbsp;[interfaceHandle](usb__ddk__types_8h.md#interfacehandle),&nbsp;uint8_t&nbsp;\*settingIndex) | 获取接口当前激活的备用设置。 |
+| [OH_Usb_SendControlReadRequest](#oh_usb_sendcontrolreadrequest)&nbsp;(uint64_t&nbsp;[interfaceHandle](usb__ddk__types_8h.md#interfacehandle),&nbsp;const&nbsp;struct&nbsp;[UsbControlRequestSetup](_usb_control_request_setup.md)&nbsp;\*setup,&nbsp;uint32_t&nbsp;[timeout](usb__ddk__types_8h.md#timeout),&nbsp;uint8_t&nbsp;\*data,&nbsp;uint32_t&nbsp;\*dataLen) | 发送控制读请求，该接口为同步接口。 |
+| [OH_Usb_SendControlWriteRequest](#oh_usb_sendcontrolwriterequest)&nbsp;(uint64_t&nbsp;[interfaceHandle](usb__ddk__types_8h.md#interfacehandle),&nbsp;const&nbsp;struct&nbsp;[UsbControlRequestSetup](_usb_control_request_setup.md)&nbsp;\*setup,&nbsp;uint32_t&nbsp;[timeout](usb__ddk__types_8h.md#timeout),&nbsp;const&nbsp;uint8_t&nbsp;\*data,&nbsp;uint32_t&nbsp;dataLen) | 发送控制写请求，该接口为同步接口。 |
+| [OH_Usb_SendPipeRequest](#oh_usb_sendpiperequest)&nbsp;(const&nbsp;struct&nbsp;[UsbRequestPipe](_usb_request_pipe.md)&nbsp;\*pipe,&nbsp;[UsbDeviceMemMap](_usb_device_mem_map.md)&nbsp;\*devMmap) | 发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 |
+| [OH_Usb_CreateDeviceMemMap](#oh_usb_createdevicememmap)&nbsp;(uint64_t&nbsp;deviceId,&nbsp;size_t&nbsp;size,&nbsp;[UsbDeviceMemMap](_usb_device_mem_map.md)&nbsp;\*\*devMmap) | 创建缓冲区。请在缓冲区使用完后，调用[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)销毁缓冲区，否则会造成资源泄露。 |
+| [OH_Usb_DestroyDeviceMemMap](#oh_usb_destroydevicememmap)&nbsp;([UsbDeviceMemMap](_usb_device_mem_map.md)&nbsp;\*devMmap) | 销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 |
+
+
+## 类型定义说明
+
+
+### UsbDdkConfigDescriptor
+
+
+```
+typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor
+```
+
+**描述:**
+
+配置描述符。
+
+
+### UsbDdkEndpointDescriptor
+
+
+```
+typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor
+```
+
+**描述:**
+
+端点描述符。
+
+
+### UsbDdkInterface
+
+
+```
+typedef struct UsbDdkInterface UsbDdkInterface
+```
+
+**描述:**
+
+USB接口，是特定接口下备用设置的集合。
+
+
+### UsbDdkInterfaceDescriptor
+
+
+```
+typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor
+```
+
+**描述:**
+
+接口描述符。
+
+
+### UsbDeviceMemMap
+
+
+```
+typedef struct UsbDeviceMemMap UsbDeviceMemMap
+```
+
+**描述:**
+
+设备内存映射，通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。
+
+
+## 枚举类型说明
+
+
+### UsbDdkErrCode
+
+
+```
+enum UsbDdkErrCode
+```
+
+**描述:**
+
+USB DDK 错误码定义。
+
+| 枚举值 | 描述 |
+| -------- | -------- |
+| USB_DDK_SUCCESS | 操作成功。 |
+| USB_DDK_FAILED | 操作失败。 |
+| USB_DDK_INVALID_PARAMETER | 非法参数。 |
+| USB_DDK_MEMORY_ERROR | 内存相关的错误，包括：内存不足、内存数据拷贝失败、内存申请失败等。 |
+| USB_DDK_INVALID_OPERATION | 非法操作。 |
+| USB_DDK_NULL_PTR | 空指针异常。 |
+| USB_DDK_DEVICE_BUSY | 设备忙。 |
+| USB_DDK_TIMEOUT | 传输超时。 |
+
+
+## 函数说明
+
+
+### OH_Usb_ClaimInterface()
+
+
+```
+int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle )
+```
+
+**描述:**
+
+声明接口。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| deviceId | 设备ID，代表要操作的设备。 |
+| interfaceIndex | 接口索引，对应USB协议中的[bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber)。 |
+| interfaceHandle | 接口操作句柄，接口声明成功后，该参数将会被赋值。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_CreateDeviceMemMap()
+
+
+```
+int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap )
+```
+
+**描述:**
+
+创建缓冲区。请在缓冲区使用完后，调用[OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap)销毁缓冲区，否则会造成资源泄露。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| deviceId | 设备ID，代表要创建缓冲区的设备。 |
+| size | 缓冲区的大小。 |
+| devMmap | 创建的缓冲区通过该参数返回给调用者。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_DestroyDeviceMemMap()
+
+
+```
+void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)
+```
+
+**描述:**
+
+销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| devMmap | 销毁由[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建的缓冲区。 |
+
+
+### OH_Usb_FreeConfigDescriptor()
+
+
+```
+void OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config)
+```
+
+**描述:**
+
+释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| config | 配置描述符，通过[OH_Usb_GetConfigDescriptor()](#oh_usb_getconfigdescriptor)获得的配置描述符。 |
+
+
+### OH_Usb_GetConfigDescriptor()
+
+
+```
+int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config )
+```
+
+**描述:**
+
+获取配置描述符。请在描述符使用完后使用[OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor)释放描述符，否则会造成内存泄露。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| deviceId | 设备ID，代表要获取配置描述符的设备。 |
+| configIndex | 配置id，对应USB协议中的[bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue)。 |
+| config | 配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_GetCurrentInterfaceSetting()
+
+
+```
+int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex )
+```
+
+**描述:**
+
+获取接口当前激活的备用设置。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
+| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_GetDeviceDescriptor()
+
+
+```
+int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc )
+```
+
+**描述:**
+
+获取设备描述符。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| deviceId | 设备ID，代表要获取描述符的设备。 |
+| desc | 设备描述符，详细定义请参考[UsbDeviceDescriptor](_usb_device_descriptor.md)。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_Init()
+
+
+```
+int32_t OH_Usb_Init (void )
+```
+
+**描述:**
+
+初始化DDK。
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_Release()
+
+
+```
+void OH_Usb_Release (void )
+```
+
+**描述:**
+
+释放DDK。
+
+
+### OH_Usb_ReleaseInterface()
+
+
+```
+int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)
+```
+
+**描述:**
+
+释放接口。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| interfaceHandle | 接口操作句柄，代表要释放的接口。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_SelectInterfaceSetting()
+
+
+```
+int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex )
+```
+
+**描述:**
+
+激活接口的备用设置。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
+| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_SendControlReadRequest()
+
+
+```
+int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen )
+```
+
+**描述:**
+
+发送控制读请求，该接口为同步接口。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
+| setup | 请求相关的参数，详细定义请参考&nbsp;[UsbControlRequestSetup](_usb_control_request_setup.md)。 |
+| timeout | 超时时间，单位为毫秒。 |
+| data | 要传输的数据。 |
+| dataLen | 表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_SendControlWriteRequest()
+
+
+```
+int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen )
+```
+
+**描述:**
+
+发送控制写请求，该接口为同步接口。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
+| setup | 请求相关的参数，详细定义请参考&nbsp;[UsbControlRequestSetup](_usb_control_request_setup.md)。 |
+| timeout | 超时时间，单位为毫秒。 |
+| data | 要传输的数据。 |
+| dataLen | 表示data的数据长度。 |
+
+**返回:**
+
+成功返回0，否则返回负数。
+
+
+### OH_Usb_SendPipeRequest()
+
+
+```
+int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap )
+```
+
+**描述:**
+
+发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。
+
+**参数:**
+
+| 名称 | 描述 |
+| -------- | -------- |
+| pipe | 要传输数据的管道信息。 |
+| devMmap | 数据缓冲区，可以通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)获得。 |
+
+**返回:**
+
+成功返回0，否则返回负数。