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 */
33typedef 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 */
45struct 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
67extern "C" {
68#endif
69
70/**
71 * @brief Defines a USB interface handle.
72 */
73typedef 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 */
90struct 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 */
108struct 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 */
118int32_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 */
129int32_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 */
139int32_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 */
151int32_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 */
163int32_t UsbFnSubmitRequestSync(struct UsbFnRequest *req, uint32_t timeout);
164
165#ifdef __cplusplus
166}
167#endif
168
169#endif /* USBFN_REQUEST_H */
170