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 types and declares the macros, enumerated variables, and\n 21 * data structures required by the USB DDK APIs. 22 * 23 * @syscap SystemCapability.Driver.USB.Extension 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file usb_ddk_types.h 30 * 31 * @brief Provides the enumerated variables, structures, and macros used in USB DDK APIs. 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_TYPES_H 41 #define USB_DDK_TYPES_H 42 43 #include <stddef.h> 44 #include <stdint.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif /* __cplusplus */ 49 /** 50 * @brief Setup data for control transfer. It corresponds to <b>Setup Data</b> in the USB protocol. 51 * 52 * @since 10 53 * @version 1.0 54 */ 55 typedef struct UsbControlRequestSetup { 56 /** Request type. */ 57 uint8_t bmRequestType; 58 /** Request command. */ 59 uint8_t bRequest; 60 /** Its meaning varies according to the request. */ 61 uint16_t wValue; 62 /** It is usually used to transfer the index or offset.\n 63 * Its meaning varies according to the request. 64 */ 65 uint16_t wIndex; 66 /** Data length. If data is transferred,\n 67 * this field indicates the number of transferred bytes. 68 */ 69 uint16_t wLength; 70 } __attribute__((aligned(8))) UsbControlRequestSetup; 71 72 /** 73 * @brief Standard device descriptor, corresponding to <b>Standard Device Descriptor</b> in the USB protocol. 74 * 75 * @since 10 76 * @version 1.0 77 */ 78 typedef struct UsbDeviceDescriptor { 79 /** Size of the descriptor, in bytes. */ 80 uint8_t bLength; 81 /** Descriptor type. */ 82 uint8_t bDescriptorType; 83 /** USB protocol release number. */ 84 uint16_t bcdUSB; 85 /** Device class code allocated by the USB-IF. */ 86 uint8_t bDeviceClass; 87 /** Device subclass code allocated by USB-IF. The value is limited by that of bDeviceClass. */ 88 uint8_t bDeviceSubClass; 89 /** Protocol code allocated by USB-IF. The value is limited by that of bDeviceClass and bDeviceSubClass. */ 90 uint8_t bDeviceProtocol; 91 /** Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid. */ 92 uint8_t bMaxPacketSize0; 93 /** Vendor ID allocated by USB-IF. */ 94 uint16_t idVendor; 95 /** Product ID allocated by the vendor. */ 96 uint16_t idProduct; 97 /** Device release number. */ 98 uint16_t bcdDevice; 99 /** Index of the string descriptor that describes the vendor. */ 100 uint8_t iManufacturer; 101 /** Index of the string descriptor that describes the product. */ 102 uint8_t iProduct; 103 /** Index of the string descriptor that describes the device SN. */ 104 uint8_t iSerialNumber; 105 /** Configuration quantity. */ 106 uint8_t bNumConfigurations; 107 } __attribute__((aligned(8))) UsbDeviceDescriptor; 108 109 /** 110 * @brief Standard configuration descriptor, corresponding to <b>Standard Configuration Descriptor</b>\n 111 * in the USB protocol. 112 * 113 * @since 10 114 * @version 1.0 115 */ 116 typedef struct UsbConfigDescriptor { 117 /** Size of the descriptor, in bytes. */ 118 uint8_t bLength; 119 /** Descriptor type. */ 120 uint8_t bDescriptorType; 121 /** Total length of the configuration descriptor, including the configuration, interface, endpoint,\n 122 * and class- or vendor-specific descriptors. 123 */ 124 uint16_t wTotalLength; 125 /** Number of interfaces supported by the configuration. */ 126 uint8_t bNumInterfaces; 127 /** Configuration index, which is used to select the configuration. */ 128 uint8_t bConfigurationValue; 129 /** Index of the string descriptor that describes the configuration. */ 130 uint8_t iConfiguration; 131 /** Configuration attributes, including the power mode and remote wakeup. */ 132 uint8_t bmAttributes; 133 /** Maximum power consumption of the bus-powered USB device, in 2 mA. */ 134 uint8_t bMaxPower; 135 } __attribute__((packed)) UsbConfigDescriptor; 136 137 /** 138 * @brief Standard interface descriptor, corresponding to <b>Standard Interface Descriptor</b> 139 * in the USB protocol. 140 * 141 * @since 10 142 * @version 1.0 143 */ 144 typedef struct UsbInterfaceDescriptor { 145 /** Size of the descriptor, in bytes. */ 146 uint8_t bLength; 147 /** Descriptor type. */ 148 uint8_t bDescriptorType; 149 /** Interface number. */ 150 uint8_t bInterfaceNumber; 151 /** Value used to select the alternate setting of the interface. */ 152 uint8_t bAlternateSetting; 153 /** Number of endpoints (excluding endpoint 0) used by the interface. */ 154 uint8_t bNumEndpoints; 155 /** Interface class code allocated by the USB-IF. */ 156 uint8_t bInterfaceClass; 157 /** Interface subclass code allocated by USB-IF. The value is limited by that of bInterfaceClass. */ 158 uint8_t bInterfaceSubClass; 159 /** Protocol code allocated by USB-IF. The value is limited by that of bInterfaceClass and bInterfaceSubClass. */ 160 uint8_t bInterfaceProtocol; 161 /** Index of the string descriptor that describes the interface. */ 162 uint8_t iInterface; 163 } __attribute__((packed)) UsbInterfaceDescriptor; 164 165 /** 166 * @brief Standard endpoint descriptor, corresponding to <b>Standard Endpoint Descriptor</b> in the USB protocol. 167 * 168 * @since 10 169 * @version 1.0 170 */ 171 typedef struct UsbEndpointDescriptor { 172 /** Size of the descriptor, in bytes. */ 173 uint8_t bLength; 174 /** Descriptor type. */ 175 uint8_t bDescriptorType; 176 /** Endpoint address, including the endpoint number and endpoint direction. */ 177 uint8_t bEndpointAddress; 178 /** Endpoint attributes, including the transfer type, synchronization type, and usage type. */ 179 uint8_t bmAttributes; 180 /** Maximum packet size supported by an endpoint. */ 181 uint16_t wMaxPacketSize; 182 /** Interval for polling endpoints for data transfer. */ 183 uint8_t bInterval; 184 /** Refresh rate for audio devices. */ 185 uint8_t bRefresh; 186 /** Endpoint synchronization address for audio devices. */ 187 uint8_t bSynchAddress; 188 } __attribute__((packed)) UsbEndpointDescriptor; 189 190 /** 191 * @brief Endpoint descriptor. 192 * 193 * @since 10 194 * @version 1.0 195 */ 196 typedef struct UsbDdkEndpointDescriptor { 197 /** Standard endpoint descriptor. */ 198 struct UsbEndpointDescriptor endpointDescriptor; 199 /** Unresolved descriptor, including class- or vendor-specific descriptors. */ 200 const uint8_t *extra; 201 /** Length of the unresolved descriptor. */ 202 uint32_t extraLength; 203 } UsbDdkEndpointDescriptor; 204 205 /** 206 * @brief Interface descriptor. 207 * 208 * @since 10 209 * @version 1.0 210 */ 211 typedef struct UsbDdkInterfaceDescriptor { 212 /** Standard interface descriptor. */ 213 struct UsbInterfaceDescriptor interfaceDescriptor; 214 /** Endpoint descriptor contained in the interface. */ 215 struct UsbDdkEndpointDescriptor *endPoint; 216 /** Unresolved descriptor, including class- or vendor-specific descriptors. */ 217 const uint8_t *extra; 218 /** Length of the unresolved descriptor. */ 219 uint32_t extraLength; 220 } UsbDdkInterfaceDescriptor; 221 222 /** 223 * @brief USB interface. 224 * 225 * @since 10 226 * @version 1.0 227 */ 228 typedef struct UsbDdkInterface { 229 /** Number of alternate settings of the interface. */ 230 uint8_t numAltsetting; 231 /** Alternate setting of the interface. */ 232 struct UsbDdkInterfaceDescriptor *altsetting; 233 } UsbDdkInterface; 234 235 /** 236 * @brief Configuration descriptor. 237 * 238 * @since 10 239 * @version 1.0 240 */ 241 typedef struct UsbDdkConfigDescriptor { 242 /** Standard configuration descriptor. */ 243 struct UsbConfigDescriptor configDescriptor; 244 /** Interfaces contained in the configuration. */ 245 struct UsbDdkInterface *interface; 246 /** Unresolved descriptor, including class- or vendor-specific descriptors. */ 247 const uint8_t *extra; 248 /** Length of the unresolved descriptor. */ 249 uint32_t extraLength; 250 } UsbDdkConfigDescriptor; 251 252 /** 253 * @brief Request pipe. 254 * 255 * @since 10 256 * @version 1.0 257 */ 258 typedef struct UsbRequestPipe { 259 /** Interface operation handle. */ 260 uint64_t interfaceHandle; 261 /** Timeout duration, in milliseconds. */ 262 uint32_t timeout; 263 /** Endpoint address. */ 264 uint8_t endpoint; 265 } __attribute__((aligned(8))) UsbRequestPipe; 266 267 /** 268 * @brief Device memory map created by calling <b>OH_Usb_CreateDeviceMemMap</b>.\n 269 * A buffer using the device memory map can provide better performance. 270 * 271 * @since 10 272 * @version 1.0 273 */ 274 typedef struct UsbDeviceMemMap { 275 /** Buffer address. */ 276 uint8_t * const address; 277 /** Buffer size. */ 278 const size_t size; 279 /** Offset of the used buffer. The default value is 0, indicating that there is no offset\n 280 * and the buffer starts from the specified address. 281 */ 282 uint32_t offset; 283 /** Length of the used buffer. By default, the value is equal to the size, indicating that\n 284 * the entire buffer is used. 285 */ 286 uint32_t bufferLength; 287 /** Length of the transferred data. */ 288 uint32_t transferedLength; 289 } UsbDeviceMemMap; 290 291 /** 292 * @brief Defines error codes for USB DDK. 293 * 294 * @since 10 295 * @version 1.0 296 */ 297 typedef enum { 298 /** @error The operation is successful. */ 299 USB_DDK_SUCCESS = 0, 300 /** @error The operation failed. 301 * @deprecate since 16 302 */ 303 USB_DDK_FAILED = -1, 304 /** @error Permission denied. 305 * @since 14 306 */ 307 USB_DDK_NO_PERM = 201, 308 /** @error Invalid parameter. */ 309 USB_DDK_INVALID_PARAMETER = 401, 310 /** @error Memory-related error, for example, insufficient memory, memory data copy failure,\n 311 * or memory application failure. 312 */ 313 USB_DDK_MEMORY_ERROR = 27400001, 314 /** @error Null pointer exception 315 * @deprecate since 16 316 */ 317 USB_DDK_NULL_PTR = -5, 318 /** @error Device busy. 319 * @deprecate since 16 320 */ 321 USB_DDK_DEVICE_BUSY = -6, 322 /** @error Invalid operation. */ 323 USB_DDK_INVALID_OPERATION = 27400002, 324 /** @error Device I/O operation failed. 325 * @since 14 326 */ 327 USB_DDK_IO_FAILED = 27400003, 328 /** @error Transmission timeout. */ 329 USB_DDK_TIMEOUT = 27400004, 330 } UsbDdkErrCode; 331 332 /** 333 * @brief all usb devices. 334 * 335 * @since 18 336 */ 337 typedef struct Usb_DeviceArray { 338 /** device id array */ 339 uint64_t* deviceIds; 340 /** Number of devices. If the value is 0, no device exists */ 341 uint32_t num; 342 } Usb_DeviceArray; 343 #ifdef __cplusplus 344 } 345 /** @} */ 346 #endif /* __cplusplus */ 347 #endif // USB_DDK_TYPES_H