1 /* 2 * Copyright (c) 2021-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 /** 17 * @file usbfn_request.h 18 * 19 * @brief Declares APIs for managing USB data requests. 20 * 21 * @since 1.0 22 * @version 1.0 23 */ 24 25 #ifndef USBFN_REQUEST_H 26 #define USBFN_REQUEST_H 27 28 #include "usb_object.h" 29 30 /** 31 * @brief Defines the USB request type. 32 */ 33 typedef enum { 34 /** Invalid request */ 35 USB_REQUEST_TYPE_INVALID, 36 /** Write request */ 37 USB_REQUEST_TYPE_PIPE_WRITE, 38 /** Read request */ 39 USB_REQUEST_TYPE_PIPE_READ, 40 } UsbFnRequestType; 41 42 /** 43 * @brief Defines a USB request. 44 */ 45 struct UsbFnRequest { 46 /** USB object */ 47 const struct UsbObject *obj; 48 /** Linked list header provided for users */ 49 struct DListHead list; 50 /** Pointer to the request data */ 51 void *buf; 52 /** Length of the request data */ 53 uint32_t length; 54 /** Request type */ 55 UsbFnRequestType type; 56 /** Request status */ 57 UsbRequestStatus status; 58 /** Number of bytes transferred to or from the buffer */ 59 uint32_t actual; 60 /** Callback for request completion */ 61 void (*complete)(uint8_t pipe, struct UsbFnRequest *req); 62 /** Pointer to the context for the callback */ 63 void *context; 64 }; 65 66 #ifdef __cplusplus 67 extern "C" { 68 #endif 69 70 /** 71 * @brief Defines a USB interface handle. 72 */ 73 typedef void *UsbFnInterfaceHandle; 74 75 /** 76 * @brief Applies for a control (EP0) request. 77 * 78 * You can use this function to apply for a control (EP0) 79 * request based on the specified USB interface handle and length. 80 * 81 * @param handle Indicates the USB interface handle. It can be set to any <b>UsbFnInterfaceHandle</b>. 82 * @param len Indicates the request data length. The maximum value is <b>2048</b>. An error will be 83 * thrown if the passed value is greater than <b>2048</b>. 84 * You are advised to set the value to the <b>bMaxPacketSize0</b> defined by the device descriptor. 85 * The data length set by <b>bMaxPacketSize0</b> prevails if a greater value is specified. 86 * 87 * @return Returns the pointer to the <b>UsbFnRequest</b> if the operation is successful; 88 * returns <b>NULL</b> otherwise. 89 */ 90 struct UsbFnRequest *UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle, uint32_t len); 91 92 /** 93 * @brief Allocates a USB request. 94 * 95 * You can use this function to allocate a USB request based on the 96 * specified USB interface handle, pipe ID, and length. 97 * 98 * @param handle Indicates the USB interface handle. 99 * @param pipe Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface. 100 * @param len Indicates the request data length. The maximum value is <b>2048</b>. An error will be thrown 101 * if the passed value is greater than <b>2048</b>. 102 * You are advised to set the value to the <b>wMaxPacketSize</b> defined by the endpoint descriptor. 103 * The data length set by <b>wMaxPacketSize</b> prevails if a greater value is specified. 104 * 105 * @return Returns the pointer to the <b>UsbFnRequest</b> if the operation is successful; 106 * returns <b>NULL</b> otherwise. 107 */ 108 struct UsbFnRequest *UsbFnAllocRequest(UsbFnInterfaceHandle handle, uint8_t pipe, uint32_t len); 109 110 /** 111 * @brief Releases a specified USB request. 112 * 113 * @param req Indicates the pointer to the USB request. 114 * 115 * @return Returns <b>0</b> if the operation is successful; 116 * returns a negative value defined in {@link UsbErrorType} otherwise. 117 */ 118 int32_t UsbFnFreeRequest(struct UsbFnRequest *req); 119 120 /** 121 * Obtains the status of a specified USB request. 122 * 123 * @param req Indicates the pointer to the USB request. 124 * @param status Indicates the pointer to the status of the USB request. 125 * 126 * @return Returns <b>0</b> if the operation is successful; 127 * returns a negative value defined in {@link UsbErrorType} otherwise. 128 */ 129 int32_t UsbFnGetRequestStatus(struct UsbFnRequest *req, UsbRequestStatus *status); 130 131 /** 132 * @brief Sends a non-isochronous USB request based on the passed request. 133 * 134 * @param req Indicates the pointer to the USB request. 135 * 136 * @return Returns <b>0</b> if the operation is successful; 137 * returns a negative value defined in {@link UsbErrorType} otherwise. 138 */ 139 int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest *req); 140 141 /** 142 * @brief Cancels a USB request based on the passed request. 143 * 144 * 145 * 146 * @param req Indicates the pointer to the USB request. 147 * 148 * @return Returns <b>0</b> if the operation is successful; 149 * returns a negative value defined in {@link UsbErrorType} otherwise. 150 */ 151 int32_t UsbFnCancelRequest(struct UsbFnRequest *req); 152 153 /** 154 * @brief Sends an isochronous USB request with a timeout interval based on the passed request. 155 * 156 * @param req Indicates the pointer to the USB request. 157 * @param timeout Indicates the timeout interval for canceling a USB request. 158 * The value <b>0</b> indicates that the system waits until the USB request is complete. 159 * 160 * @return Returns <b>0</b> if the operation is successful; 161 * returns a negative value defined in {@link UsbErrorType} otherwise. 162 */ 163 int32_t UsbFnSubmitRequestSync(struct UsbFnRequest *req, uint32_t timeout); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif /* USBFN_REQUEST_H */ 170