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