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_ddk_interface.h 29 * 30 * @brief Declares the data types and interface functions provided by the host of the USB driver development kit (DDK). 31 * 32 * @since 1.0 33 * @version 1.0 34 */ 35 #ifndef USB_INTERFACE_H 36 #define USB_INTERFACE_H 37 38 #include "usb_session.h" 39 40 /** 41 * @brief Defines the default ID of the USB control interface. 42 */ 43 #define USB_CTRL_INTERFACE_ID 0xFF 44 45 /** 46 * @brief Defines the request object type. 47 * 48 * It will be filled in the corresponding field in {@link UsbControlRequest}. 49 */ 50 typedef enum { 51 /** USB device object */ 52 USB_REQUEST_TARGET_DEVICE, 53 /** Interface object */ 54 USB_REQUEST_TARGET_INTERFACE, 55 /** Endpoint object */ 56 USB_REQUEST_TARGET_ENDPOINT, 57 /** Other objects */ 58 USB_REQUEST_TARGET_OTHER, 59 } UsbRequestTargetType; 60 61 /** 62 * @brief Defines the control request type. 63 * 64 * It will be filled in the corresponding field in {@link UsbControlRequest}. 65 */ 66 typedef enum { 67 /** Standard request */ 68 USB_REQUEST_TYPE_STANDARD, 69 /** Class request */ 70 USB_REQUEST_TYPE_CLASS, 71 /** Vendor request */ 72 USB_REQUEST_TYPE_VENDOR, 73 } UsbControlRequestType; 74 75 /** 76 * @brief Defines the request data direction. 77 * 78 * It will be filled in the corresponding field in {@link UsbControlRequest} or {@link UsbRequestParamsData}. 79 */ 80 typedef enum { 81 /** Data transfer from the host to the device */ 82 USB_REQUEST_DIR_TO_DEVICE, 83 /** Data transfer from the device to the host */ 84 USB_REQUEST_DIR_FROM_DEVICE, 85 } UsbRequestDirection; 86 87 /** 88 * @brief Defines the request parameter type. 89 * 90 * It will be filled in the corresponding field in {@link UsbRequestParams} to indicate whether the request parameter 91 * is of the control type or data type. 92 */ 93 typedef enum { 94 /** Control type */ 95 USB_REQUEST_PARAMS_CTRL_TYPE, 96 /** Data type */ 97 USB_REQUEST_PARAMS_DATA_TYPE, 98 } UsbRequestParamsType; 99 100 /** 101 * @brief Defines the USB request type. 102 */ 103 typedef enum { 104 /** Invalid request */ 105 USB_REQUEST_TYPE_INVALID, 106 /** Control request */ 107 USB_REQUEST_TYPE_DEVICE_CONTROL, 108 /** Write request */ 109 USB_REQUEST_TYPE_PIPE_WRITE, 110 /** Read request */ 111 USB_REQUEST_TYPE_PIPE_READ, 112 } UsbRequestPipeType; 113 114 /** 115 * @brief Defines a USB interface operation handle. 116 */ 117 typedef void *UsbInterfaceHandle; 118 119 /** 120 * @brief Defines a USB pipe information object. 121 */ 122 struct UsbPipeInfo { 123 /** Interface ID of the current pipe */ 124 uint8_t interfaceId; 125 /** Pipe ID, which is used to search the specified pipe */ 126 uint8_t pipeId; 127 /** Pipe address, which is used to fill the I/O request through {@link UsbRequestFill} */ 128 uint8_t pipeAddress; 129 /** Pipe type */ 130 UsbPipeType pipeType; 131 /** Pipe direction */ 132 UsbPipeDirection pipeDirection; 133 /** Maximum size of packets received and sent over the pipe */ 134 uint16_t maxPacketSize; 135 /** Interval for the host to query the pipe */ 136 uint8_t interval; 137 }; 138 139 /** 140 * @brief Defines a USB pipe object. 141 */ 142 struct UsbPipe { 143 /** USB basic object */ 144 struct UsbObject object; 145 /** USB pipe information. For details, see {@link UsbPipeInfo}. */ 146 struct UsbPipeInfo info; 147 }; 148 149 /** 150 * @brief Defines a USB interface information object. 151 */ 152 struct UsbInterfaceInfo { 153 /** Interface index */ 154 uint8_t interfaceIndex; 155 /** Index of the enabled interface */ 156 uint8_t altSettings; 157 /** Index of the current enabled interface */ 158 uint8_t curAltSetting; 159 /** Pipe quantity */ 160 uint8_t pipeNum; 161 /** Interface class */ 162 uint8_t interfaceClass; 163 /** Interface subclass */ 164 uint8_t interfaceSubClass; 165 /** Interface protocol */ 166 uint8_t interfaceProtocol; 167 }; 168 169 /** 170 * @brief Defines a USB interface object. 171 */ 172 struct UsbInterface { 173 /** USB basic object */ 174 struct UsbObject object; 175 /** USB interface information. For details, see {@link UsbInterfaceInfo}. */ 176 struct UsbInterfaceInfo info; 177 }; 178 179 /** 180 * @brief Defines USB request completion information. 181 */ 182 struct UsbRequestCompInfo { 183 /** Request pipe type. For details, see {@link UsbRequestPipeType}. */ 184 UsbRequestPipeType type; 185 /** Pointer to the user data buffer */ 186 unsigned char *buffer; 187 /** The address of data buffer */ 188 uint32_t length; 189 /** Actual length of the data sent at request completion */ 190 uint32_t actualLength; 191 /** Request status. For details, see {@link UsbRequestStatus}. */ 192 UsbRequestStatus status; 193 /** Pointer to the user data */ 194 void *userData; 195 }; 196 197 /** 198 * @brief Defines a USB request. 199 * 200 * There are two types of request objects: <b>UsbObject</b> (USB basic object) and <b>UsbRequestCompInfo</b> 201 * (USB request completion information ). You can query the current request execution status through the USB request 202 * completion information. 203 * The isochronous (block) request and non-isochronous (non-block) request share this data structure but use different 204 * application interfaces. The isochronous (block) request uses the <b>UsbSubmitRequestSync</b> interface, 205 * whereas the non-isochronous (non-block) request uses the <b>UsbSubmitRequestAsync</b> interface. 206 */ 207 struct UsbRequest { 208 /** USB basic object */ 209 struct UsbObject object; 210 /** USB request completion information. For details, see {@link UsbRequestCompInfo}. */ 211 struct UsbRequestCompInfo compInfo; 212 }__attribute__((aligned(4))); 213 214 /** 215 * @brief Defines the callback function for completion of a user request. It will be used to fill the 216 * {@link UsbRequestParams} object. 217 */ 218 typedef void (*UsbRequestCallback)(struct UsbRequest *request); 219 220 /** 221 * @brief Defines a control request object, which will be used to fill in the {@link UsbRequestParams} object. 222 */ 223 struct UsbControlRequest { 224 /** Type of the received control request packet. For details, see {@link UsbRequestTargetType}. */ 225 UsbRequestTargetType target; 226 /** Control request type. For details, see {@link UsbControlRequestType}. */ 227 UsbControlRequestType reqType; 228 /** Request data direction. For details, see {@link UsbRequestDirection}. */ 229 UsbRequestDirection directon; 230 /** Request command */ 231 uint8_t request; 232 /** Value set based on the request */ 233 uint16_t value; 234 /** Index set based on the request to identify an endpoint or interface */ 235 uint16_t index; 236 /** Pointer to the transmitted data */ 237 void *buffer; 238 /** Length of the transmitted data */ 239 uint32_t length; 240 }; 241 242 /** 243 * @brief Defines data request parameters, which will be used to fill the {@link UsbRequestParams} object. 244 */ 245 struct UsbRequestParamsData { 246 /** Number of transmitted data packets in isochronous transfer */ 247 int32_t numIsoPackets; 248 /** Request data direction. For details, see {@link UsbRequestDirection}. */ 249 UsbRequestDirection directon; 250 /** Pointer to the request data */ 251 unsigned char *buffer; 252 /** Length of the request data */ 253 uint32_t length; 254 }; 255 256 /** 257 * @brief Defines a USB request parameter object, which can be {@link UsbControlRequest} (control request parameter) 258 * or {@link UsbRequestParamsData} (data request parameter). 259 */ 260 struct UsbRequestParams { 261 /** Interface ID */ 262 uint8_t interfaceId; 263 /** Pipe ID. For details, see {@link UsbPipeInfo}. */ 264 uint8_t pipeId; 265 /** Pipe address. For details, see {@link UsbPipeInfo}. */ 266 uint8_t pipeAddress; 267 /** Callback function for request completion on the user side. For details, see {@link UsbRequestCallback}. */ 268 UsbRequestCallback callback; 269 /** Pointer to the user data */ 270 void *userData; 271 /** Request timeout interval */ 272 unsigned int timeout; 273 /** Request parameter type */ 274 UsbRequestParamsType requestType; 275 /** Request parameter */ 276 union { 277 /** Control request parameter. For details, see {@link UsbControlRequest}. */ 278 struct UsbControlRequest ctrlReq; 279 /** Data request parameter. For details, see {@link UsbRequestParamsData}. */ 280 struct UsbRequestParamsData dataReq; 281 }; 282 }; 283 284 /** 285 * @brief Initializes the USB DDK on the host side. 286 * 287 * You can use this function to allocate and initialize resources. 288 * 289 * @param session Indicates the double pointer to the session context. It can be set to <b>NULL</b> or a value defined 290 * in {@link UsbSession}. 291 * 292 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 293 * otherwise. 294 */ 295 int32_t UsbInitHostSdk(struct UsbSession **session); 296 297 /** 298 * @brief Exits the USB DDK on the host side. 299 * 300 * You can use this function to release occupied resources. 301 * 302 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 303 * {@link UsbSession}. 304 * 305 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 306 * otherwise. 307 */ 308 int32_t UsbExitHostSdk(const struct UsbSession *session); 309 310 /** 311 * @brief Obtains a USB interface object based on a specified interface index in unforce state. 312 * 313 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 314 * {@link UsbSession}. 315 * @param busNum Indicates the USB device bus number. 316 * @param usbAddr Indicates the USB device address. 317 * @param interfaceIndex Indicates the index of the interface object to be obtained. This parameter is defined in the 318 * <b>UsbInterfaceInfo</b> structure. 319 * The default index of the control interface is <b>0xFF</b>. 320 * 321 * @return Returns the pointer to the <b>UsbInterface</b> structure if the operation is successful; returns <b>NULL</b> 322 * otherwise. 323 */ 324 struct UsbInterface *UsbClaimInterfaceUnforce(const struct UsbSession *session, uint8_t busNum, 325 uint8_t usbAddr, uint8_t interfaceIndex); 326 327 /** 328 * @brief Obtains a USB interface object based on a specified interface index in force state. 329 * 330 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in 331 * {@link UsbSession}. 332 * @param busNum Indicates the USB device bus number. 333 * @param usbAddr Indicates the USB device address. 334 * @param interfaceIndex Indicates the index of the interface object to be obtained. This parameter is defined in the 335 * <b>UsbInterfaceInfo</b> structure. 336 * The default index of the control interface is <b>0xFF</b>. 337 * 338 * @return Returns the pointer to the <b>UsbInterface</b> structure if the operation is successful; returns <b>NULL</b> 339 * otherwise. 340 */ 341 struct UsbInterface *UsbClaimInterface(const struct UsbSession *session, uint8_t busNum, 342 uint8_t usbAddr, uint8_t interfaceIndex); 343 344 /** 345 * @brief Releases a USB interface object. 346 * 347 * @param interfaceObj Indicates the pointer to the USB interface object to release. 348 * 349 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 350 * otherwise. 351 */ 352 int32_t UsbReleaseInterface(const struct UsbInterface *interfaceObj); 353 354 /** 355 * @brief Adds or removes an interface. 356 * 357 * @param status Indicates the interface operation status. 358 * @param interfaceObj Indicates the pointer to the USB interface object to add or remove. 359 * 360 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 361 * otherwise. 362 */ 363 int32_t UsbAddOrRemoveInterface(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr, 364 uint8_t interfaceIndex, UsbInterfaceStatus status); 365 366 /** 367 * @brief Opens a USB interface object. 368 * 369 * @param interfaceObj Indicates the pointer to the USB interface object to open. 370 * 371 * @return Returns the pointer to the <b>UsbInterfaceHandle</b> if the operation is successful; returns <b>NULL</b> 372 * otherwise. 373 */ 374 UsbInterfaceHandle *UsbOpenInterface(const struct UsbInterface *interfaceObj); 375 376 /** 377 * @brief Closes a USB interface object. 378 * 379 * @param interfaceHandle Indicates the pointer to the handle of the USB interface object to close. 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 UsbCloseInterface(const UsbInterfaceHandle *interfaceHandle); 385 386 /** 387 * @brief Sets the optional configuration. 388 * 389 * @param interfaceHandle Indicates the pointer to the USB interface handle. 390 * @param settingIndex Indicates the index of the optional configuration. 391 * 392 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 393 * otherwise. 394 */ 395 int32_t UsbSelectInterfaceSetting(const UsbInterfaceHandle *interfaceHandle, uint8_t settingIndex, 396 struct UsbInterface **interfaceObj); 397 398 /** 399 * @brief Obtains pipe information from the specified optional configuration. 400 * 401 * @param interfaceHandle Indicates the pointer to the USB interface handle. 402 * @param settingIndex Indicates the index of the optional configuration. 403 * @param pipeIndex Indicates the pipe index. 404 * @param pipeInfo Indicates the pointer to the obtained pipe information. 405 * 406 */ 407 int32_t UsbGetPipeInfo(const UsbInterfaceHandle *interfaceHandle, uint8_t settingIndex, 408 uint8_t pipeId, struct UsbPipeInfo *pipeInfo); 409 410 /** 411 * @brief Clears the status of a specified pipe. 412 * 413 * @param interfaceHandle Indicates the pointer to the USB interface handle. 414 * @param pipeAddress Indicates the pipe address. 415 * 416 */ 417 int32_t UsbClearInterfaceHalt(const UsbInterfaceHandle *interfaceHandle, uint8_t pipeAddress); 418 419 /** 420 * @brief Allocates a USB request. 421 * 422 * I/O requests are allocated based on the size of the user space. If they are used to send isochronous transfer 423 * packets, extra space will be allocated. 424 * 425 * @param interfaceHandle Indicates the pointer to the USB interface handle. 426 * @param isoPackets Indicates the number of isochronous transfer packets. For details, see {@link UsbPipeType}. 427 * @param length Indicates the size of the user space to allocate. 428 * 429 * @return Returns the pointer to the <b>UsbRequest</b> structure if the operation is successful; returns <b>NULL</b> 430 * otherwise. 431 */ 432 struct UsbRequest *UsbAllocRequest(const UsbInterfaceHandle *interfaceHandle, int32_t isoPackets, int32_t length); 433 434 /** 435 * @brief Releases a request object. 436 * 437 * @param request Indicates the pointer to the USB request. 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 UsbFreeRequest(const struct UsbRequest *request); 443 444 /** 445 * @brief Sends an asynchronous request. 446 * 447 * @param request Indicates the pointer to the USB request. 448 * 449 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 450 * otherwise. 451 */ 452 int32_t UsbSubmitRequestAsync(const struct UsbRequest *request); 453 454 /** 455 * @brief Fills an I/O request based on specified parameters. 456 * 457 * @param request Indicates the pointer to the USB request. 458 * @param interfaceHandle Indicates the pointer to the USB interface handle. 459 * @param params Indicates the pointer to a list of parameters to fill. For details, see {@link UsbRequestParams}. 460 * 461 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS} 462 * otherwise. 463 */ 464 int32_t UsbFillRequest(const struct UsbRequest *request, const UsbInterfaceHandle *interfaceHandle, 465 const struct UsbRequestParams *params); 466 467 /** 468 * @brief Cancels an asynchronous USB request. 469 470 * @param request Indicates the pointer to the USB request. 471 * 472 * @return Returns <b>UsbInterfaceHandle</b> if the operation is successful; returns <b>NULL</b> otherwise. 473 */ 474 int32_t UsbCancelRequest(const struct UsbRequest *request); 475 476 /** 477 * @brief Sends a synchronous USB request. 478 * 479 * @param request Indicates the pointer to the USB request. 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 UsbSubmitRequestSync(const struct UsbRequest *request); 485 int32_t UsbMemTestTrigger(bool enable); 486 487 #endif /* USB_INTERFACE_H */ 488 /** @} */