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