1 /* 2 * Copyright (c) 2023-2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup UsbDdk 18 * @{ 19 * 20 * @brief Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous\n 21 * data transfer over USB pipes, and implement control transfer and interrupt transfer, etc. 22 * 23 * @syscap SystemCapability.Driver.USB.Extension 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file usb_ddk_api.h 30 * 31 * @brief Declares the USB DDK APIs used by the USB host to access USB devices. 32 * 33 * @kit DriverDevelopmentKit 34 * @library libusb_ndk.z.so 35 * @syscap SystemCapability.Driver.USB.Extension 36 * @since 10 37 * @version 1.0 38 */ 39 40 #ifndef USB_DDK_API_H 41 #define USB_DDK_API_H 42 43 #include <stdint.h> 44 45 #include "ddk_types.h" 46 #include "usb_ddk_types.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif /* __cplusplus */ 51 52 /** 53 * @brief Initializes the DDK. 54 * 55 * @permission ohos.permission.ACCESS_DDK_USB 56 * @return {@link USB_DDK_SUCCESS} the operation is successful. 57 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed or internal error. 58 * {@link USB_DDK_NO_PERM} permission check failed. 59 * {@link USB_DDK_MEMORY_ERROR} memory allocation failed. 60 * @since 10 61 * @version 1.0 62 */ 63 int32_t OH_Usb_Init(void); 64 65 /** 66 * @brief Releases the DDK. 67 * 68 * @permission ohos.permission.ACCESS_DDK_USB 69 * @since 10 70 * @version 1.0 71 */ 72 void OH_Usb_Release(void); 73 74 /** 75 * @brief Releases the DDK. 76 * 77 * @permission ohos.permission.ACCESS_DDK_USB 78 * @return {@link USB_DDK_SUCCESS} the operation is successful. 79 * {@link USB_DDK_NO_PERM} permission check failed. 80 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 81 * @since 18 82 * @version 1.0 83 */ 84 int32_t OH_Usb_ReleaseResource(void); 85 86 /** 87 * @brief Obtains the USB device descriptor. 88 * 89 * @permission ohos.permission.ACCESS_DDK_USB 90 * @param deviceId ID of the device whose descriptor is to be obtained. 91 * @param desc Standard device descriptor defined in the USB protocol. 92 * @return {@link USB_DDK_SUCCESS} the operation is successful. 93 * {@link USB_DDK_NO_PERM} permission check failed. 94 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 95 * {@link USB_DDK_INVALID_PARAMETER} desc is null. 96 * @since 10 97 * @version 1.0 98 */ 99 int32_t OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc); 100 101 /** 102 * @brief Obtains the configuration descriptor. To avoid memory leakage, use <b>OH_Usb_FreeConfigDescriptor</b>\n 103 * to release a descriptor after use. 104 * 105 * @permission ohos.permission.ACCESS_DDK_USB 106 * @param deviceId ID of the device whose configuration descriptor is to be obtained. 107 * @param configIndex Configuration index, which corresponds to <b>bConfigurationValue</b> in the USB protocol. 108 * @param config Configuration descriptor, which includes the standard configuration descriptor defined in the\n 109 * USB protocol and the associated interface descriptor and endpoint descriptor. 110 * @return {@link USB_DDK_SUCCESS} the operation is successful. 111 * {@link USB_DDK_NO_PERM} permission check failed. 112 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 113 * {@link USB_DDK_INVALID_PARAMETER} config is null. 114 * {@link USB_DDK_IO_FAILED} data IO exception. 115 * {@link USB_DDK_MEMORY_ERROR} memory allocation failed. 116 * @since 10 117 * @version 1.0 118 */ 119 int32_t OH_Usb_GetConfigDescriptor( 120 uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor ** const config); 121 122 /** 123 * @brief Releases the configuration descriptor. To avoid memory leakage, use <b>OH_Usb_FreeConfigDescriptor</b>\n 124 * to release a descriptor after use. 125 * 126 * @permission ohos.permission.ACCESS_DDK_USB 127 * @param config Configuration descriptor obtained by calling <b>OH_Usb_GetConfigDescriptor</b>. 128 * @since 10 129 * @version 1.0 130 */ 131 void OH_Usb_FreeConfigDescriptor(struct UsbDdkConfigDescriptor * const config); 132 133 /** 134 * @brief Claims a USB interface. 135 * 136 * @permission ohos.permission.ACCESS_DDK_USB 137 * @param deviceId ID of the device to be operated. 138 * @param interfaceIndex Interface index, which corresponds to <b>bInterfaceNumber</b> in the USB protocol. 139 * @param interfaceHandle Interface operation handle. After the interface is claimed successfully, a value will be\n 140 * assigned to this parameter. 141 * @return {@link USB_DDK_SUCCESS} the operation is successful. 142 * {@link USB_DDK_NO_PERM} permission check failed. 143 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 144 * {@link USB_DDK_INVALID_PARAMETER} interfaceHandle is null. 145 * {@link USB_DDK_MEMORY_ERROR} memory exceeds limit. 146 * @since 10 147 * @version 1.0 148 */ 149 int32_t OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle); 150 151 /** 152 * @brief Releases a USB interface. 153 * 154 * @permission ohos.permission.ACCESS_DDK_USB 155 * @param interfaceHandle Interface operation handle. 156 * @return {@link USB_DDK_SUCCESS} the operation is successful. 157 * {@link USB_DDK_NO_PERM} permission check failed. 158 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 159 * {@link USB_DDK_INVALID_PARAMETER} parameter error. 160 * @since 10 161 * @version 1.0 162 */ 163 int32_t OH_Usb_ReleaseInterface(uint64_t interfaceHandle); 164 165 /** 166 * @brief Activates the alternate setting of the USB interface. 167 * 168 * @permission ohos.permission.ACCESS_DDK_USB 169 * @param interfaceHandle Interface operation handle. 170 * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n 171 * in the USB protocol. 172 * @return {@link USB_DDK_SUCCESS} the operation is successful. 173 * {@link USB_DDK_NO_PERM} permission check failed. 174 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 175 * {@link USB_DDK_INVALID_PARAMETER} parameter error. 176 * @since 10 177 * @version 1.0 178 */ 179 int32_t OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex); 180 181 /** 182 * @brief Obtains the activated alternate setting of the USB interface. 183 * 184 * @permission ohos.permission.ACCESS_DDK_USB 185 * @param interfaceHandle Interface operation handle. 186 * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n 187 * in the USB protocol. 188 * @return {@link USB_DDK_SUCCESS} the operation is successful. 189 * {@link USB_DDK_NO_PERM} permission check failed. 190 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 191 * {@link USB_DDK_INVALID_PARAMETER} settingIndex is null. 192 * @since 10 193 * @version 1.0 194 */ 195 int32_t OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t *settingIndex); 196 197 /** 198 * @brief Sends a control read transfer request. This API works in a synchronous manner. 199 * 200 * @permission ohos.permission.ACCESS_DDK_USB 201 * @param interfaceHandle Interface operation handle. 202 * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol. 203 * @param timeout Timeout duration, in milliseconds. 204 * @param data Data to be transferred. 205 * @param dataLen Data length. The return value indicates the length of the actually read data. 206 * @return {@link USB_DDK_SUCCESS} the operation is successful. 207 * {@link USB_DDK_NO_PERM} permission check failed. 208 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 209 * {@link USB_DDK_INVALID_PARAMETER} setup is null or data is null or dataLen is null or dataLen is less than\n 210 * size of the read data. 211 * {@link USB_DDK_MEMORY_ERROR} the memory of read data copies failed. 212 * {@link USB_DDK_IO_FAILED} data IO exception. 213 * {@link USB_DDK_TIMEOUT} interface timeout. 214 * @since 10 215 * @version 1.0 216 */ 217 int32_t OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, 218 uint32_t timeout, uint8_t *data, uint32_t *dataLen); 219 220 /** 221 * @brief Sends a control write transfer request. This API works in a synchronous manner. 222 * 223 * @permission ohos.permission.ACCESS_DDK_USB 224 * @param interfaceHandle Interface operation handle. 225 * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol. 226 * @param timeout Timeout duration, in milliseconds. 227 * @param data Data to be transferred. 228 * @param dataLen Data length. 229 * @return {@link USB_DDK_SUCCESS} the operation is successful. 230 * {@link USB_DDK_NO_PERM} permission check failed. 231 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 232 * {@link USB_DDK_INVALID_PARAMETER} setup is null or data is null. 233 * {@link USB_DDK_MEMORY_ERROR} the memory of read data copies failed. 234 * {@link USB_DDK_IO_FAILED} data IO exception. 235 * {@link USB_DDK_TIMEOUT} interface timeout. 236 * @since 10 237 * @version 1.0 238 */ 239 int32_t OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, 240 uint32_t timeout, const uint8_t *data, uint32_t dataLen); 241 242 /** 243 * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n 244 * and bulk transfer. 245 * 246 * @permission ohos.permission.ACCESS_DDK_USB 247 * @param pipe Pipe used to transfer data. 248 * @param devMmap Device memory map, which can be obtained by calling <b>OH_Usb_CreateDeviceMemMap</b>. 249 * @return {@link USB_DDK_SUCCESS} the operation is successful. 250 * {@link USB_DDK_NO_PERM} permission check failed. 251 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 252 * {@link USB_DDK_INVALID_PARAMETER} pipe is null or devMmap is null or address of devMmap is null. 253 * {@link USB_DDK_MEMORY_ERROR} the memory of read data copies failed. 254 * {@link USB_DDK_IO_FAILED} data IO exception. 255 * {@link USB_DDK_TIMEOUT} interface timeout. 256 * @since 10 257 * @version 1.0 258 */ 259 int32_t OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap); 260 261 /** 262 * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n 263 * and bulk transfer. 264 * 265 * @permission ohos.permission.ACCESS_DDK_USB 266 * @param pipe Pipe used to transfer data. 267 * @param ashmem Shared memory, which can be obtained by calling <b>OH_DDK_CreateAshmem</b>. 268 * @return {@link USB_DDK_SUCCESS} the operation is successful. 269 * {@link USB_DDK_NO_PERM} permission check failed. 270 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 271 * {@link USB_DDK_INVALID_PARAMETER} pipe is null or ashmem is null or address of ashmem is null. 272 * {@link USB_DDK_MEMORY_ERROR} the memory of read data copies failed. 273 * {@link USB_DDK_IO_FAILED} data IO exception. 274 * {@link USB_DDK_TIMEOUT} interface timeout. 275 * @since 12 276 */ 277 int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem); 278 279 /** 280 * @brief Creates a buffer. To avoid resource leakage, destroy a buffer by calling\n 281 * <b>OH_Usb_DestroyDeviceMemMap</b> after use. 282 * 283 * @permission ohos.permission.ACCESS_DDK_USB 284 * @param deviceId ID of the device for which the buffer is to be created. 285 * @param size Buffer size. 286 * @param devMmap Data memory map, through which the created buffer is returned to the caller. 287 * @return {@link USB_DDK_SUCCESS} the operation is successful. 288 * {@link USB_DDK_NO_PERM} permission check failed. 289 * {@link USB_DDK_INVALID_PARAMETER} devMmap is null. 290 * {@link USB_DDK_MEMORY_ERROR} mmap failed or alloc memory of devMmap failed. 291 * @since 10 292 * @version 1.0 293 */ 294 int32_t OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap); 295 296 /** 297 * @brief Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. 298 * 299 * @permission ohos.permission.ACCESS_DDK_USB 300 * @param devMmap Device memory map created by calling <b>OH_Usb_CreateDeviceMemMap</b>. 301 * @since 10 302 * @version 1.0 303 */ 304 void OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap); 305 306 /** 307 * @brief Obtain USB devices. 308 * 309 * @permission ohos.permission.ACCESS_DDK_USB 310 * @param devices USB device array. 311 * @return {@link USB_DDK_SUCCESS} the operation is successful. 312 * {@link USB_DDK_NO_PERM} permission check failed. 313 * {@link USB_DDK_INVALID_OPERATION} connect usb ddk service failed. 314 * {@link USB_DDK_INVALID_PARAMETER} devices is null. 315 * @since 18 316 */ 317 int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices); 318 /** @} */ 319 #ifdef __cplusplus 320 } 321 #endif /* __cplusplus */ 322 323 #endif // USB_DDK_API_H