1 /* 2 * Copyright (c) 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 * @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 /** 67 * @brief Defines a USB interface handle. 68 */ 69 typedef void *UsbFnInterfaceHandle; 70 71 /** 72 * @brief Applies for a control (EP0) request. 73 * 74 * You can use this function to apply for a control (EP0) 75 * request based on the specified USB interface handle and length. 76 * 77 * @param handle Indicates the USB interface handle. It can be set to any <b>UsbFnInterfaceHandle</b>. 78 * @param len Indicates the request data length. The maximum value is <b>2048</b>. An error will be 79 * thrown if the passed value is greater than <b>2048</b>. 80 * You are advised to set the value to the <b>bMaxPacketSize0</b> defined by the device descriptor. 81 * The data length set by <b>bMaxPacketSize0</b> prevails if a greater value is specified. 82 * 83 * @return Returns the pointer to the <b>UsbFnRequest</b> if the operation is successful; 84 * returns <b>NULL</b> otherwise. 85 */ 86 struct UsbFnRequest *UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle, uint32_t len); 87 88 /** 89 * @brief Allocates a USB request. 90 * 91 * You can use this function to allocate a USB request based on the 92 * specified USB interface handle, pipe ID, and length. 93 * 94 * @param handle Indicates the USB interface handle. 95 * @param pipe Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface. 96 * @param len Indicates the request data length. The maximum value is <b>2048</b>. An error will be thrown 97 * if the passed value is greater than <b>2048</b>. 98 * You are advised to set the value to the <b>wMaxPacketSize</b> defined by the endpoint descriptor. 99 * The data length set by <b>wMaxPacketSize</b> prevails if a greater value is specified. 100 * 101 * @return Returns the pointer to the <b>UsbFnRequest</b> if the operation is successful; 102 * returns <b>NULL</b> otherwise. 103 */ 104 struct UsbFnRequest *UsbFnAllocRequest(UsbFnInterfaceHandle handle, uint8_t pipe, uint32_t len); 105 106 /** 107 * @brief Releases a specified USB request. 108 * 109 * @param req Indicates the pointer to the USB request. 110 * 111 * @return Returns <b>0</b> if the operation is successful; 112 * returns a negative value defined in {@link UsbErrorType} otherwise. 113 */ 114 int32_t UsbFnFreeRequest(struct UsbFnRequest *req); 115 116 /** 117 * Obtains the status of a specified USB request. 118 * 119 * @param req Indicates the pointer to the USB request. 120 * @param status Indicates the pointer to the status of the USB request. 121 * 122 * @return Returns <b>0</b> if the operation is successful; 123 * returns a negative value defined in {@link UsbErrorType} otherwise. 124 */ 125 int32_t UsbFnGetRequestStatus(struct UsbFnRequest *req, UsbRequestStatus *status); 126 127 /** 128 * @brief Sends a non-isochronous USB request based on the passed request. 129 * 130 * @param req Indicates the pointer to the USB request. 131 * 132 * @return Returns <b>0</b> if the operation is successful; 133 * returns a negative value defined in {@link UsbErrorType} otherwise. 134 */ 135 int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest *req); 136 137 /** 138 * @brief Cancels a USB request based on the passed request. 139 * 140 * 141 * 142 * @param req Indicates the pointer to the USB request. 143 * 144 * @return Returns <b>0</b> if the operation is successful; 145 * returns a negative value defined in {@link UsbErrorType} otherwise. 146 */ 147 int32_t UsbFnCancelRequest(struct UsbFnRequest *req); 148 149 /** 150 * @brief Sends an isochronous USB request with a timeout interval based on the passed request. 151 * 152 * @param req Indicates the pointer to the USB request. 153 * @param timeout Indicates the timeout interval for canceling a USB request. 154 * The value <b>0</b> indicates that the system waits until the USB request is complete. 155 * 156 * @return Returns <b>0</b> if the operation is successful; 157 * returns a negative value defined in {@link UsbErrorType} otherwise. 158 */ 159 int32_t UsbFnSubmitRequestSync(struct UsbFnRequest *req, uint32_t timeout); 160 161 #endif /* USBFN_REQUEST_H */ 162