1 /* 2 * Copyright (c) 2020-2021 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 USB 18 * @{ 19 * 20 * @brief Declares USB-related APIs, including the custom data types and functions used to obtain descriptors, 21 * interface objects, and request objects, and to submit requests. 22 * 23 * @since 1.0 24 * @version 1.0 25 */ 26 27 /** 28 * @file usb_raw_api.h 29 * 30 * @brief Defines the data types and interface functions provided by the USB driver development kit (DDK) in 31 * expert mode. 32 * 33 * @since 1.0 34 * @version 1.0 35 */ 36 #ifndef USB_RAW_API_H 37 #define USB_RAW_API_H 38 39 #include "usb_ddk.h" 40 #include "usb_session.h" 41 42 /** 43 * @brief Defines the maximum number of USB interfaces. 44 */ 45 #define USB_MAXINTERFACES 32 46 47 /** 48 * @brief Defines a pointer to the USB device handle in expert mode. 49 */ 50 typedef void *UsbRawDevice; 51 52 /** 53 * @brief Defines a pointer to the USB device operation handle in expert mode. 54 */ 55 typedef void *UsbRawHandle; 56 57 /** 58 * @brief Defines a pointer to the callback called when a user request in expert mode is complete. This callback 59 * function is used to fill the <b>#UsbRawFillRequestData</b> object. 60 */ 61 typedef void (*UsbRawRequestCallback)(const void *requestArg); 62 63 /** 64 * @brief Defines a control request object. 65 */ 66 struct UsbControlRequestData { 67 /** Control request type */ 68 uint8_t requestType; 69 /** Request command */ 70 uint8_t requestCmd; 71 /** Value set based on the request */ 72 uint16_t value; 73 /** Index set based on the request to identify an endpoint or interface */ 74 uint16_t index; 75 /** Length of the transmitted data */ 76 uint16_t length; 77 /** Timeout interval of the control request */ 78 unsigned int timeout; 79 /** Pointer to the transmitted data */ 80 unsigned char *data; 81 }; 82 83 /** 84 * @brief Defines request parameters for filling the <b>UsbRawSendBulkRequest</b> or <b>UsbRawSendInterruptRequest</b> 85 * function. 86 * Request data to be sent 87 */ 88 struct UsbRequestData { 89 /** Address of the endpoint that sends the request */ 90 unsigned char endPoint; 91 /** Pointer to the request data */ 92 unsigned char *data; 93 /** Length of the request data */ 94 uint32_t length; 95 /** Pointer to the transmitted bytes of the request */ 96 int32_t *requested; 97 /** Request timeout interval */ 98 unsigned int timeout; 99 }; 100 101 /** 102 * @brief Defines descriptor parameters in expert mode. 103 */ 104 struct UsbRawDescriptorParam { 105 /** Descriptor type */ 106 uint8_t descType; 107 /** Descriptor index */ 108 uint8_t descIndex; 109 /** Length of the data to read */ 110 int32_t length; 111 }; 112 113 /** 114 * @brief Defines a request object in expert mode. 115 */ 116 struct UsbRawRequest { 117 /** Pointer to the data in the buffer */ 118 unsigned char *buffer; 119 /** Length of the user data */ 120 int32_t length; 121 /** Actual length of the data sent at request completion */ 122 int32_t actualLength; 123 /** Request status. For details, see {@link UsbRequestStatus}. */ 124 UsbRequestStatus status; 125 /** Pointer to the user data */ 126 void *userData; 127 }; 128 129 /** 130 * @brief Defines a request data object in expert mode. 131 */ 132 struct UsbRawFillRequestData { 133 /** Endpoint of the request data */ 134 unsigned char endPoint; 135 /** Pointer to the request data buffer */ 136 unsigned char *buffer; 137 /** Length of the request data */ 138 uint32_t length; 139 /** Number of transmitted data packets in isochronous transfer */ 140 int32_t numIsoPackets; 141 /** Callback function for request completion on the user side. For details, see {@link UsbRawRequestCallback}. */ 142 UsbRawRequestCallback callback; 143 /** Pointer to the user data */ 144 void *userData; 145 /** Request timeout interval */ 146 unsigned int timeout; 147 }; 148 149 /** 150 * @brief Defines the standard USB endpoint descriptor. 151 */ 152 struct UsbRawEndpointDescriptor { 153 /** Standard USB endpoint descriptor */ 154 struct UsbEndpointDescriptor endpointDescriptor; 155 /** Pointer to the extra descriptor */ 156 const unsigned char *extra; 157 /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */ 158 int32_t extraLength; 159 }; 160 161 /** 162 * @brief Defines the standard USB interface descriptor. 163 */ 164 struct UsbRawInterfaceDescriptor { 165 /** Standard USB interface descriptor */ 166 struct UsbInterfaceDescriptor interfaceDescriptor; 167 /** Pointer to the endpoint descriptor array */ 168 const struct UsbRawEndpointDescriptor *endPoint; 169 /** Pointer to the extra descriptor */ 170 const unsigned char *extra; 171 /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */ 172 int32_t extraLength; 173 }; 174 175 /** 176 * @brief Defines alternate settings for a particular USB interface. 177 */ 178 struct UsbRawInterface { 179 /** Number of alternate settings that belong to the interface. The value must be a non-negative number. */ 180 uint8_t numAltsetting; 181 /** Interface descriptor array. Its length is determined by the numAltsetting field. */ 182 const struct UsbRawInterfaceDescriptor altsetting[]; 183 }; 184 185 /** 186 * @brief Defines the standard USB configuration descriptor. 187 */ 188 struct UsbRawConfigDescriptor { 189 /** Standard USB configuration descriptor */ 190 struct UsbConfigDescriptor configDescriptor; 191 /** Pointer to the interface array supported by the configuration. The maximum number of interfaces is determined 192 * by USB_MAXINTERFACES. */ 193 const struct UsbRawInterface *interface[USB_MAXINTERFACES]; 194 /** Pointer to the extra descriptor */ 195 const unsigned char *extra; 196 /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */ 197 int32_t extraLength; 198 }; 199 200 /** 201 * @brief Initializes the USB DDK in expert mode. 202 * 203 * You can use this function to allocate and initialize resources. 204 * 205 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 206 * {@link UsbSession}. 207 * 208 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 209 * otherwise. 210 */ 211 int32_t UsbRawInit(struct UsbSession **session); 212 213 /** 214 * @brief Exits the expert mode of the USB DDK. 215 * 216 * You can use this function to release occupied resources. 217 * 218 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 219 * {@link UsbSession}. 220 * 221 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 222 * otherwise. 223 */ 224 int32_t UsbRawExit(const struct UsbSession *session); 225 226 /** 227 * @brief Opens a USB device object. 228 * 229 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 230 * {@link UsbSession}. 231 * @param busNum Indicates the USB device bus number. 232 * @param usbAddr Indicates the USB device address. 233 * 234 * @return Returns the pointer to the <b>UsbRawHandle</b> if the operation is successful; returns <b>NULL</b> 235 * otherwise. 236 */ 237 UsbRawHandle *UsbRawOpenDevice(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr); 238 239 /** 240 * @brief Closes a USB device object. 241 * 242 * @param devHandle Indicates the pointer to the device handle. 243 * 244 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 245 * otherwise. 246 */ 247 int32_t UsbRawCloseDevice(const UsbRawHandle *devHandle); 248 249 /** 250 * @brief Performs control transfer. 251 * 252 * @param request Indicates the pointer to the request to send. 253 * @param devHandle Indicates the pointer to the device handle. 254 * @param requestData Indicates the pointer to the request data to send. 255 * 256 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 257 * otherwise. 258 */ 259 int32_t UsbRawSendControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 260 const struct UsbControlRequestData *requestData); 261 262 /** 263 * @brief Performs bulk transfer. 264 * 265 * @param request Indicates the pointer to the request to send. 266 * @param devHandle Indicates the pointer to the device handle. 267 * @param requestData Indicates the pointer to the request data to send. 268 * 269 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 270 * otherwise. 271 */ 272 int32_t UsbRawSendBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 273 const struct UsbRequestData *requestData); 274 /** 275 * @brief Performs interrupt transfer. 276 * 277 * @param request Indicates the pointer to the request to send. 278 * @param devHandle Indicates the pointer to the device handle. 279 * @param requestData Indicates the pointer to the request data to send. 280 * 281 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 282 * otherwise. 283 */ 284 int32_t UsbRawSendInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 285 const struct UsbRequestData *requestData); 286 287 /** 288 * @brief Obtains the device configuration descriptor based on a specified device ID. 289 * 290 * @param rawDev Indicates the pointer to the USB raw device. 291 * @param configIndex Indicates the ID of the device configuration descriptor. 292 * @param config Indicates the double pointer to the device configuration descriptor. 293 * 294 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 295 * otherwise. 296 */ 297 int32_t UsbRawGetConfigDescriptor( 298 const UsbRawDevice *rawDev, uint8_t configIndex, struct UsbRawConfigDescriptor **config); 299 300 /** 301 * @brief Releases the memory space of the device configuration descriptor. 302 * 303 * @param config Indicates the pointer to the device configuration descriptor. 304 * 305 */ 306 void UsbRawFreeConfigDescriptor(const struct UsbRawConfigDescriptor *config); 307 308 /** 309 * @brief Obtains the active device configuration. 310 * 311 * @param devHandle Indicates the pointer to the device handle. 312 * @param config Indicates the pointer to the device configuration descriptor. 313 * 314 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 315 * otherwise. 316 */ 317 int32_t UsbRawGetConfiguration(const UsbRawHandle *devHandle, int32_t *config); 318 319 /** 320 * @brief Sets the active device configuration. 321 * 322 * @param devHandle Indicates the pointer to the device handle. 323 * @param config Indicates the device configuration descriptor. 324 * 325 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 326 * otherwise. 327 */ 328 int32_t UsbRawSetConfiguration(const UsbRawHandle *devHandle, int32_t config); 329 330 /** 331 * @brief Obtains descriptor information. 332 * 333 * @param request Indicates the pointer to the request to send. 334 * @param devHandle Indicates the pointer to the device handle. 335 * @param param Indicates the pointer to the descriptor parameter. For details, see {@link UsbRawDescriptorParam}. 336 * @param data Indicates the pointer to the descriptor address. 337 * 338 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 339 * otherwise. 340 */ 341 int32_t UsbRawGetDescriptor(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 342 const struct UsbRawDescriptorParam *param, const unsigned char *data); 343 344 /** 345 * @brief Obtains the device pointer based on a specified device handle. 346 * 347 * @param devHandle Indicates the pointer to the device handle. 348 * 349 * @return Returns the device pointer if any; returns <b>NULL</b> otherwise. For details, see {@link UsbRawDevice}. 350 */ 351 UsbRawDevice *UsbRawGetDevice(const UsbRawHandle *devHandle); 352 353 /** 354 * @brief Obtains the USB device descriptor of a specified device. 355 * 356 * @param rawDev Indicates the pointer to the USB raw device. 357 * @param desc Indicates the pointer to the device descriptor. 358 * 359 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 360 * otherwise. 361 */ 362 int32_t UsbRawGetDeviceDescriptor(const UsbRawDevice *rawDev, struct UsbDeviceDescriptor *desc); 363 364 /** 365 * @brief Declares the interface on the given device handle. 366 * 367 * @param devHandle Indicates the pointer to the device handle of the interface to declare. 368 * @param interfaceNumber Indicates the number of the interface to declare. 369 * 370 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 371 * otherwise. 372 */ 373 int32_t UsbRawClaimInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber); 374 375 /** 376 * @brief Releases the previously declared interface. 377 * 378 * @param devHandle Indicates the pointer to the device handle of the interface to release. 379 * @param interfaceNumber Indicates the number of the interface to release. 380 * 381 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 382 * otherwise. 383 */ 384 int32_t UsbRawReleaseInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber); 385 386 /** 387 * @brief Resets a device. 388 * 389 * @param devHandle Indicates the pointer to the device handle. 390 * 391 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 392 * otherwise. 393 */ 394 int32_t UsbRawResetDevice(const UsbRawHandle *devHandle); 395 396 /** 397 * @brief Allocates a transfer request with a specified number of isochronous transfer packet descriptors. 398 * 399 * For details about isochronous transfer, see {@link UsbPipeType}. 400 * 401 * @param devHandle Indicates the pointer to the device handle. 402 * @param isoPackets Indicates the number of isochronous transfer packet descriptors to allocate. The value must be a 403 * non-negative number. 404 * @param length Indicates the size of the user space to allocate. 405 * 406 * @return Returns the pointer to the <b>UsbHostRequest</b> structure if the operation is successful; returns 407 * <b>NULL</b> otherwise. 408 */ 409 struct UsbRawRequest *UsbRawAllocRequest(const UsbRawHandle *devHandle, int32_t isoPackets, int32_t length); 410 411 /** 412 * @brief Releases the previously allocated transfer request. 413 * 414 * @param request Indicates the pointer to the transfer request to release. 415 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 416 * otherwise. 417 */ 418 int32_t UsbRawFreeRequest(const struct UsbRawRequest *request); 419 420 /** 421 * @brief Fills required information in a bulk transfer request. 422 * 423 * @param request Indicates the pointer to the request to send. 424 * @param devHandle Indicates the pointer to the device handle. 425 * @param fillRequestData Indicates the pointer to the request data to fill. 426 * 427 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 428 * otherwise. 429 */ 430 int32_t UsbRawFillBulkRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 431 const struct UsbRawFillRequestData *fillData); 432 433 /** 434 * @brief Fills required information in control transfer configuration packets. 435 * 436 * @param setup Indicates the pointer to the control information. 437 * @param requestData Indicates the pointer to the request data to fill. 438 * 439 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 440 * otherwise. 441 */ 442 int32_t UsbRawFillControlSetup(const unsigned char *setup, const struct UsbControlRequestData *requestData); 443 444 /** 445 * @brief Fills required information in a control transfer request. 446 * 447 * @param request Indicates the pointer to the request to send. 448 * @param devHandle Indicates the pointer to the device handle. 449 * @param fillRequestData Indicates the pointer to the request data to fill. 450 * 451 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 452 * otherwise. 453 */ 454 int32_t UsbRawFillControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 455 const struct UsbRawFillRequestData *fillData); 456 457 /** 458 * @brief Fills required information in an interrupt transfer request. 459 * 460 * @param request Indicates the pointer to the request to send. 461 * @param devHandle Indicates the pointer to the device handle. 462 * @param fillRequestData Indicates the pointer to the request data to fill. 463 * 464 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 465 * otherwise. 466 */ 467 int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 468 const struct UsbRawFillRequestData *fillData); 469 470 /** 471 * @brief Fills required information in an isochronous transfer request. 472 * 473 * @param request Indicates the pointer to the request to send. 474 * @param devHandle Indicates the pointer to the device handle. 475 * @param fillRequestData Indicates the pointer to the request data to fill. 476 * 477 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 478 * otherwise. 479 */ 480 int32_t UsbRawFillIsoRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle, 481 const struct UsbRawFillRequestData *fillData); 482 483 /** 484 * @brief Submits a transfer request. 485 * 486 * @param request Indicates the pointer to the request to submit. 487 * 488 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 489 * otherwise. 490 */ 491 int32_t UsbRawSubmitRequest(const struct UsbRawRequest *request); 492 493 /** 494 * @brief Cancels a transfer request. 495 * 496 * @param request Indicates the pointer to the request to cancel. 497 * 498 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 499 * otherwise. 500 */ 501 int32_t UsbRawCancelRequest(const struct UsbRawRequest *request); 502 503 /** 504 * @brief Defines the handle for a transfer request event. 505 * 506 * @param devHandle Indicates the pointer to the device handle. 507 * 508 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 509 * otherwise. 510 */ 511 int32_t UsbRawHandleRequests(const UsbRawHandle *devHandle); 512 513 #endif /* USB_RAW_API_H */ 514 /** @} */ 515