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_interface.h
18 *
19 * @brief Declares USB interface-specific definitions.
20 *
21 * @since 1.0
22 * @version 1.0
23 */
24
25#ifndef USBFN_INTERFACE_H
26#define USBFN_INTERFACE_H
27
28#include "usb_object.h"
29#include "usbfn_request.h"
30
31/**
32 * @brief Defines USB interfaces of the unspecified class.
33 */
34#define USB_INTERFACE_CLASS_UNSPEC              0x00
35
36/**
37 * @brief Defines USB interfaces of the Audio class.
38 */
39#define USB_INTERFACE_CLASS_AUDIO               0x01
40
41/**
42 * @brief Defines USB interfaces of the Communication Device Class (CDC).
43 */
44#define USB_INTERFACE_CLASS_CDC                 0x02
45
46/**
47 * @brief Defines USB interfaces of the Human Interface Device (HID) class.
48 */
49#define USB_INTERFACE_CLASS_HID                 0x03
50
51/**
52 * @brief Defines USB interfaces of the Physical class.
53 */
54#define USB_INTERFACE_CLASS_PHYSICAL            0x05
55
56/**
57 * @brief Defines USB interfaces of the Image class.
58 */
59#define USB_INTERFACE_CLASS_IMAGE               0x06
60
61/**
62 * @brief Defines USB interfaces of the Printer class.
63 */
64#define USB_INTERFACE_CLASS_PRINTER             0x07
65
66/**
67 * @brief Defines USB interfaces of the Mass Storage (MSD) class.
68 */
69#define USB_INTERFACE_CLASS_MASS_STORAGE        0x08
70
71/**
72 * @brief Defines USB interfaces of the Hub class.
73 */
74#define USB_INTERFACE_CLASS_HUB                 0x09
75
76/**
77 * @brief Defines USB interfaces of the CDC-Data class.
78 */
79#define USB_INTERFACE_CLASS_CDC_DATA            0x0a
80
81/**
82 * @brief Defines USB interfaces of the Smart Card class.
83 */
84#define USB_INTERFACE_CLASS_SMARTCARD           0x0b
85
86/**
87 * @brief Defines USB interfaces of the Firmware Upgrade class.
88 */
89#define USB_INTERFACE_CLASS_FIRM_UPD            0x0c
90
91/**
92 * @brief Defines USB interfaces of the Content Security class.
93 */
94#define USB_INTERFACE_CLASS_SECURITY            0x0d
95
96/**
97 * @brief Defines USB interfaces of the Video class.
98 */
99#define USB_INTERFACE_CLASS_VIDEO               0x0e
100
101/**
102 * @brief Defines USB interfaces of the Diagnostic Device class.
103 */
104#define USB_INTERFACE_CLASS_DIAGNOSTIC          0xdc
105
106/**
107 * @brief Defines USB interfaces of the Wireless Controller class.
108 */
109#define USB_INTERFACE_CLASS_WIRELESS            0xe0
110
111/**
112 * @brief Defines USB interfaces of the Miscellaneous class.
113 */
114#define USB_INTERFACE_CLASS_IAD                 0xef
115
116/**
117 * @brief Defines USB interfaces of the Application Specific class.
118 */
119#define USB_INTERFACE_CLASS_APP_SPEC            0xfe
120
121/**
122 * @brief Defines USB interfaces of the Vendor Specific class.
123 */
124#define USB_INTERFACE_CLASS_VENDOR              0xff
125
126/**
127 * @brief Defines the USB device event status.
128 */
129typedef enum {
130    /** USB binding event */
131    USBFN_STATE_BIND,
132    /** USB unbinding event */
133    USBFN_STATE_UNBIND,
134    /** USB enabling event */
135    USBFN_STATE_ENABLE,
136    /** USB disabling event */
137    USBFN_STATE_DISABLE,
138    /** USB connection setup event */
139    USBFN_STATE_SETUP,
140    /** USB suspending event */
141    USBFN_STATE_SUSPEND,
142    /** USB resuming event */
143    USBFN_STATE_RESUME,
144} UsbFnDeviceState;
145
146/**
147 * @brief Defines structure parameters for the USB interface request.
148 */
149struct UsbFnCtrlRequest {
150    /** Request type */
151    uint8_t reqType;
152    /** Specific request */
153    uint8_t request;
154    /** Request data value */
155    uint16_t value;
156    /** Request index value */
157    uint16_t index;
158    /**
159    * Number of bytes in the data communication phase, which must be less than the
160    * value of <b>bMaxPacketSize0</b> defined in the device descriptor
161    */
162    uint16_t length;
163} __attribute__((packed));
164
165/**
166 * @brief Defines the structure of the events received by the USB interface.
167 */
168struct UsbFnEvent {
169    /** Pointer to the received parameters of the control request */
170    struct UsbFnCtrlRequest *setup;
171    UsbFnDeviceState        type;
172    void                    *context;
173};
174
175/**
176 * @brief Defines the USB interface information.
177 */
178struct UsbFnInterfaceInfo {
179    /** Interface index */
180    uint8_t index;
181    /** Number of pipes */
182    uint8_t numPipes;
183    /** Interface class */
184    uint8_t interfaceClass;
185    /** Interface subclass */
186    uint8_t subclass;
187    /** Interface protocol */
188    uint8_t protocol;
189    /** Interface configuration index */
190    uint8_t configIndex;
191};
192
193/**
194 * @brief Defines USB interface objects.
195 */
196struct UsbFnInterface {
197    /** Pointer to the USB object */
198    const struct UsbObject    *object;
199    /** USB interface information */
200    struct UsbFnInterfaceInfo info;
201};
202
203/**
204 * @brief Defines the USB pipe information.
205 */
206struct UsbFnPipeInfo {
207    /** Pipe ID */
208    uint8_t           id;
209    /** Pipe type */
210    UsbPipeType       type;
211    /** Pipe direction */
212    UsbPipeDirection  dir;
213    /** Maximum size of data packets that can be sent or received over the pipe */
214    uint16_t          maxPacketSize;
215    /** Data transmission interval of the pipe */
216    uint8_t           interval;
217};
218
219/**
220 * @brief Defines callback called when endpoint 0 receives a control event.
221 *
222 * This function needs to be defined by the function driver.
223 *
224 * @param event Indicates the pointer to the event information, including the event type and request.
225 */
226typedef void (*UsbFnEventCallback)(struct UsbFnEvent *event);
227
228/**
229 * @brief Defines the callback called when the function interface obtains or sets custom attributes.
230 *
231 * This function needs to be defined by the function driver.
232 *
233 * @param interface Indicates the pointer to the USB interface object.
234 * @param name Indicates the pointer to the attribute name of the string type.
235 * @param value Indicates the pointer to the attribute value of the string type.
236 *
237 * @return Returns <b>0</b> if the operation is successful;
238 * returns a negative value defined in {@link UsbErrorType} otherwise.
239 */
240typedef int32_t (*UsbFnPropCallback)(const struct UsbFnInterface *intf, const char *name, const char *value);
241
242/**
243 * @brief Defines custom attribute information.
244 */
245struct UsbFnRegistInfo {
246    /** Pointer to the attribute name */
247    const char *name;
248    /** Pointer to the attribute value */
249    const char *value;
250    /** Pointer to the callback for the request of obtaining custom attributes */
251    UsbFnPropCallback getProp;
252    /** Pointer to the callback for the request of setting custom attributes */
253    UsbFnPropCallback setProp;
254};
255
256#ifdef __cplusplus
257extern "C" {
258#endif
259
260/**
261 * @brief Defines the callback called when the USB interface starts a thread to receive EP0 events,
262 * such as the setup event.
263 *
264 * @param interface Indicates the pointer to the USB interface object.
265 * @param eventMask Indicates the type of the event to be processed.
266 * The event is defined by <b>UsbFnDeviceState</b>.
267 * Each bit of <b>eventMask</b> indicates an event.
268 * For example, if the value of <b>eventMask</b> is <b>0xff</b>, all events are received;
269 * if the value of <b>eventMask</b> is <b>0x01</b>, only the <b>USBFN_STATE_BIND</b> event is received.
270 * @param callback Indicates the callback function called after a request is processed.
271 * It needs to be defined by the application.
272 * @param context Indicates the pointer to the private context data.
273 *
274 * @return Returns <b>0</b> if the operation is successful; returns a negative value
275 * defined in {@link UsbErrorType} otherwise.
276 */
277int32_t UsbFnStartRecvInterfaceEvent(
278    struct UsbFnInterface *interface, uint32_t eventMask, UsbFnEventCallback callback, void *context);
279
280/**
281 * @brief Defines the callback called when the USB interface stops receiving EP0 events.
282 *
283 * @param interface Indicates the pointer to the USB interface object.
284 *
285 * @return Returns <b>0</b> if the operation is successful; returns a negative
286 * value defined in {@link UsbErrorType} otherwise.
287 */
288int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface);
289
290/**
291 * @brief Enables a USB interface.
292 *
293 * This function is mainly used to initialize a request queue and open a pipe.
294 *
295 * @param interface Indicates the pointer to the USB interface object.
296 *
297 * @return Returns a <b>#UsbFnInterfaceHandle</b> containing the USB interface information
298 * if the operation is successful; returns <b>NULL</b> otherwise.
299 */
300UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface);
301
302/**
303 * @brief Disables a USB interface.
304 *
305 * This function is mainly used to close a pipe and delete a request queue.
306 *
307 * @param UsbFnInterfaceHandle Indicates the handle of the USB interface object.
308 *
309 * @return Returns <b>0</b> if the operation is successful; returns a negative value
310 * defined in {@link UsbErrorType} otherwise.
311 */
312int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle);
313
314/**
315 * @brief Obtains USB pipe information based on the specified pipe ID.
316 *
317 * @param interface Indicates the pointer to the USB interface object.
318 * @param pipeId Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface.
319 * @param info Indicates the pointer to the obtained pipe information.
320 *
321 * @return Returns <b>0</b> if the operation is successful; returns a negative
322 * value defined in {@link UsbErrorType} otherwise.
323 */
324int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface *interface, uint8_t pipeId, struct UsbFnPipeInfo *info);
325
326/**
327 * @brief Registers custom attributes for a USB interface.
328 *
329 * In addition to custom attributes, you can use this function to register the callback function
330 * for the request of obtaining and setting custom attributes.
331 *
332 * @param interface Indicates the pointer to the USB interface object.
333 * @param registInfo Indicates the pointer to the attribute information.
334 *
335 * @return Returns <b>0</b> if the operation is successful; returns a negative
336 * value defined in {@link UsbErrorType} otherwise.
337 */
338int32_t UsbFnRegistInterfaceProp(const struct UsbFnInterface *interface, const struct UsbFnRegistInfo *registInfo);
339
340/**
341 * @brief Obtains custom attributes of a USB interface.
342 *
343 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID,
344 * attributes of the USB interface defined in the HCS file, and attributes registered
345 * in the code at the application layer.
346 * For example, if <b>name</b> is <b>idVendor</b> when obtaining the VID, the obtained value will be
347 * stored in <b>value</b> as a hex string.
348 *
349 * @param interface Indicates the pointer to the USB interface object.
350 * @param name Indicates the pointer to the attribute name of the string type.
351 * @param value Indicates the pointer to the attribute value of the string type. Except integer data,
352 * which is a string converted from hex data, all the other types of data are strings by default.
353 *
354 * @return Returns <b>0</b> if the operation is successful; returns a negative
355 * value defined in {@link UsbErrorType} otherwise.
356 */
357int32_t UsbFnGetInterfaceProp(const struct UsbFnInterface *interface, const char *name, char *value);
358
359/**
360 * @brief Sets custom attributes of a USB interface.
361 *
362 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID,
363 * attributes of the USB interface defined in the HCS file, and attributes registered
364 * in the code at the application layer.
365 * For example, if <b>name</b> is <b>idVendor</b> when setting the VID, the set value will be
366 * stored in <b>value</b> as a hex string.
367 *
368 * @param interface Indicates the pointer to the USB interface object.
369 * @param name Indicates the pointer to the attribute name of the string type.
370 * @param value Indicates the pointer to the attribute value of the string type. Except integer data,
371 * which is a string converted from hex data, all the other types of data are strings by default.
372 *
373 * @return Returns <b>0</b> if the operation is successful; returns a negative
374 * value defined in {@link UsbErrorType} otherwise.
375 */
376int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface *interface, const char *name, const char *value);
377
378#ifdef __cplusplus
379}
380#endif
381
382#endif /* USBFN_INTERFACE_H */
383