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