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