1/*
2 * Copyright (c) 2020-2022 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_raw_api.h
29 *
30 * @brief Defines the data types and interface functions provided by the USB driver development kit (DDK) in
31 * expert mode.
32 *
33 * @since 1.0
34 * @version 1.0
35 */
36#ifndef USB_RAW_API_H
37#define USB_RAW_API_H
38
39#include "usb_ddk.h"
40#include "usb_session.h"
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/**
47 * @brief Defines the maximum number of USB interfaces.
48 */
49#define USB_MAXINTERFACES 32
50
51/**
52 * @brief Defines a pointer to the USB device handle in expert mode.
53 */
54typedef void *UsbRawDevice;
55
56/**
57 * @brief Defines a pointer to the USB device operation handle in expert mode.
58 */
59typedef void *UsbRawHandle;
60
61/**
62 * @brief Defines a pointer to the callback called when a user request in expert mode is complete. This callback
63 * function is used to fill the <b>#UsbRawFillRequestData</b> object.
64 */
65typedef void (*UsbRawRequestCallback)(const void *requestArg);
66
67/**
68 * @brief Defines a control request object.
69 */
70struct UsbControlRequestData {
71    /** Control request type */
72    uint8_t requestType;
73    /** Request command */
74    uint8_t requestCmd;
75    /** Value set based on the request */
76    uint16_t value;
77    /** Index set based on the request to identify an endpoint or interface */
78    uint16_t index;
79    /** Length of the transmitted data */
80    uint16_t length;
81    /** Timeout interval of the control request */
82    unsigned int timeout;
83    /** Pointer to the transmitted data */
84    unsigned char *data;
85};
86
87/**
88 * @brief Defines request parameters for filling the <b>UsbRawSendBulkRequest</b> or <b>UsbRawSendInterruptRequest</b>
89 * function.
90 * Request data to be sent
91 */
92struct UsbRequestData {
93    /** Address of the endpoint that sends the request */
94    unsigned char endPoint;
95    /** Pointer to the request data */
96    unsigned char *data;
97    /** Length of the request data */
98    uint32_t length;
99    /** Pointer to the transmitted bytes of the request */
100    int32_t *requested;
101    /** Request timeout interval */
102    unsigned int timeout;
103};
104
105/**
106 * @brief Defines descriptor parameters in expert mode.
107 */
108struct UsbRawDescriptorParam {
109    /** Descriptor type */
110    uint8_t descType;
111    /** Descriptor index */
112    uint8_t descIndex;
113    /** Length of the data to read */
114    int32_t length;
115};
116
117/**
118 * @brief Defines a request object in expert mode.
119 */
120struct UsbRawRequest {
121    /** Pointer to the data in the buffer */
122    unsigned char *buffer;
123    /** Length of the user data */
124    int32_t length;
125    /** Actual length of the data sent at request completion */
126    int32_t actualLength;
127    /** Request status. For details, see {@link UsbRequestStatus}. */
128    UsbRequestStatus status;
129    /** Pointer to the user data */
130    void *userData;
131};
132
133/**
134 * @brief Defines a request data object in expert mode.
135 */
136struct UsbRawFillRequestData {
137    /** Endpoint of the request data */
138    unsigned char endPoint;
139    /** Pointer to the request data buffer */
140    unsigned char *buffer;
141    /** Length of the request data */
142    uint32_t length;
143    /** Number of transmitted data packets in isochronous transfer */
144    int32_t numIsoPackets;
145    /** Callback function for request completion on the user side. For details, see {@link UsbRawRequestCallback}. */
146    UsbRawRequestCallback callback;
147    /** Pointer to the user data */
148    void *userData;
149    /** Request timeout interval */
150    unsigned int timeout;
151};
152
153/**
154 * @brief Defines the standard USB endpoint descriptor.
155 */
156struct UsbRawEndpointDescriptor {
157    /** Standard USB endpoint descriptor */
158    struct UsbEndpointDescriptor endpointDescriptor;
159    /** Pointer to the extra descriptor */
160    const unsigned char *extra;
161    /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */
162    int32_t extraLength;
163};
164
165/**
166 * @brief Defines the standard USB interface descriptor.
167 */
168struct UsbRawInterfaceDescriptor {
169    /** Standard USB interface descriptor */
170    struct UsbInterfaceDescriptor interfaceDescriptor;
171    /** Pointer to the endpoint descriptor array */
172    const struct UsbRawEndpointDescriptor *endPoint;
173    /** Pointer to the extra descriptor */
174    const unsigned char *extra;
175    /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */
176    int32_t extraLength;
177};
178
179/**
180 * @brief Defines alternate settings for a particular USB interface.
181 */
182struct UsbRawInterface {
183    /** Number of alternate settings that belong to the interface. The value must be a non-negative number. */
184    uint8_t numAltsetting;
185    /** Interface descriptor array. Its length is determined by the numAltsetting field. */
186    const struct UsbRawInterfaceDescriptor altsetting[];
187};
188
189/**
190 * @brief Defines the standard USB configuration descriptor.
191 */
192struct UsbRawConfigDescriptor {
193    /** Standard USB configuration descriptor */
194    struct UsbConfigDescriptor configDescriptor;
195    /** Pointer to the interface array supported by the configuration. The maximum number of interfaces is determined
196     * by USB_MAXINTERFACES. */
197    const struct UsbRawInterface *interface[USB_MAXINTERFACES];
198    /** Pointer to the extra descriptor */
199    const unsigned char *extra;
200    /** Length of the extra descriptor, in bytes. The value must be a non-negative number. */
201    int32_t extraLength;
202};
203
204/**
205 * @brief Initializes the USB DDK in expert mode.
206 *
207 * You can use this function to allocate and initialize resources.
208 *
209 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in
210 * {@link UsbSession}.
211 *
212 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
213 * otherwise.
214 */
215int32_t UsbRawInit(struct UsbSession **session);
216
217/**
218 * @brief Exits the expert mode of the USB DDK.
219 *
220 * You can use this function to release occupied resources.
221 *
222 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in
223 * {@link UsbSession}.
224 *
225 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
226 * otherwise.
227 */
228int32_t UsbRawExit(const struct UsbSession *session);
229
230/**
231 * @brief Opens a USB device object.
232 *
233 * @param session Indicates the pointer to the session context. It can be set to <b>NULL</b> or a value defined in
234 * {@link UsbSession}.
235 * @param busNum Indicates the USB device bus number.
236 * @param usbAddr Indicates the USB device address.
237 *
238 * @return Returns the pointer to the <b>UsbRawHandle</b> if the operation is successful; returns <b>NULL</b>
239 * otherwise.
240 */
241UsbRawHandle *UsbRawOpenDevice(const struct UsbSession *session, uint8_t busNum, uint8_t usbAddr);
242
243/**
244 * @brief Closes a USB device object.
245 *
246 * @param devHandle Indicates the pointer to the device handle.
247 *
248 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
249 * otherwise.
250 */
251int32_t UsbRawCloseDevice(const UsbRawHandle *devHandle);
252
253/**
254 * @brief Performs control transfer.
255 *
256 * @param request Indicates the pointer to the request to send.
257 * @param devHandle Indicates the pointer to the device handle.
258 * @param requestData Indicates the pointer to the request data to send.
259 *
260 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
261 * otherwise.
262 */
263int32_t UsbRawSendControlRequest(const struct UsbRawRequest *request, const UsbRawHandle *devHandle,
264    const struct UsbControlRequestData *requestData);
265
266/**
267 * @brief Performs bulk transfer.
268 *
269 * @param request Indicates the pointer to the request to send.
270 * @param devHandle Indicates the pointer to the device handle.
271 * @param requestData Indicates the pointer to the request data to send.
272 *
273 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
274 * otherwise.
275 */
276int32_t UsbRawSendBulkRequest(
277    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);
278/**
279 * @brief Performs interrupt transfer.
280 *
281 * @param request Indicates the pointer to the request to send.
282 * @param devHandle Indicates the pointer to the device handle.
283 * @param requestData Indicates the pointer to the request data to send.
284 *
285 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
286 * otherwise.
287 */
288int32_t UsbRawSendInterruptRequest(
289    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRequestData *requestData);
290
291/**
292 * @brief Obtains the device configuration descriptor based on a specified device ID.
293 *
294 * @param rawDev Indicates the pointer to the USB raw device.
295 * @param configIndex Indicates the ID of the device configuration descriptor.
296 * @param config Indicates the double pointer to the device configuration descriptor.
297 *
298 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
299 * otherwise.
300 */
301int32_t UsbRawGetConfigDescriptor(
302    const UsbRawDevice *rawDev, uint8_t configIndex, struct UsbRawConfigDescriptor ** const config);
303
304/**
305 * @brief Releases the memory space of the device configuration descriptor.
306 *
307 * @param config Indicates the pointer to the device configuration descriptor.
308 *
309 */
310void UsbRawFreeConfigDescriptor(const struct UsbRawConfigDescriptor *config);
311
312/**
313 * @brief Obtains the active device configuration.
314 *
315 * @param devHandle Indicates the pointer to the device handle.
316 * @param config Indicates the pointer to the device configuration descriptor.
317 *
318 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
319 * otherwise.
320 */
321int32_t UsbRawGetConfiguration(const UsbRawHandle * const devHandle, int32_t *config);
322
323/**
324 * @brief Sets the active device configuration.
325 *
326 * @param devHandle Indicates the pointer to the device handle.
327 * @param config Indicates the device configuration descriptor.
328 *
329 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
330 * otherwise.
331 */
332int32_t UsbRawSetConfiguration(const UsbRawHandle *devHandle, int32_t config);
333
334/**
335 * @brief Obtains descriptor information.
336 *
337 * @param request Indicates the pointer to the request to send.
338 * @param devHandle Indicates the pointer to the device handle.
339 * @param param Indicates the pointer to the descriptor parameter. For details, see {@link UsbRawDescriptorParam}.
340 * @param data Indicates the pointer to the descriptor address.
341 *
342 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
343 * otherwise.
344 */
345int32_t UsbRawGetDescriptor(const struct UsbRawRequest *request, const UsbRawHandle *devHandle,
346    const struct UsbRawDescriptorParam *param, const unsigned char *data);
347
348/**
349 * @brief Obtains the device pointer based on a specified device handle.
350 *
351 * @param devHandle Indicates the pointer to the device handle.
352 *
353 * @return Returns the device pointer if any; returns <b>NULL</b> otherwise. For details, see {@link UsbRawDevice}.
354 */
355UsbRawDevice *UsbRawGetDevice(const UsbRawHandle * const devHandle);
356
357/**
358 * @brief Obtains the USB device descriptor of a specified device.
359 *
360 * @param rawDev Indicates the pointer to the USB raw device.
361 * @param desc Indicates the pointer to the device descriptor.
362 *
363 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
364 * otherwise.
365 */
366int32_t UsbRawGetDeviceDescriptor(const UsbRawDevice *rawDev, struct UsbDeviceDescriptor *desc);
367
368/**
369 * @brief Declares the interface on the given device handle.
370 *
371 * @param devHandle Indicates the pointer to the device handle of the interface to declare.
372 * @param interfaceNumber Indicates the number of the interface to declare.
373 *
374 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
375 * otherwise.
376 */
377int32_t UsbRawClaimInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber);
378
379/**
380 * @brief Releases the previously declared interface.
381 *
382 * @param devHandle Indicates the pointer to the device handle of the interface to release.
383 * @param interfaceNumber Indicates the number of the interface to release.
384 *
385 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
386 * otherwise.
387 */
388int32_t UsbRawReleaseInterface(const UsbRawHandle *devHandle, int32_t interfaceNumber);
389
390/**
391 * @brief Resets a device.
392 *
393 * @param devHandle Indicates the pointer to the device handle.
394 *
395 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
396 * otherwise.
397 */
398int32_t UsbRawResetDevice(const UsbRawHandle *devHandle);
399
400/**
401 * @brief Allocates a transfer request with a specified number of isochronous transfer packet descriptors.
402 *
403 * For details about isochronous transfer, see {@link UsbPipeType}.
404 *
405 * @param devHandle Indicates the pointer to the device handle.
406 * @param isoPackets Indicates the number of isochronous transfer packet descriptors to allocate. The value must be a
407 * non-negative number.
408 * @param length Indicates the size of the user space to allocate.
409 *
410 * @return Returns the pointer to the <b>UsbHostRequest</b> structure if the operation is successful; returns
411 * <b>NULL</b> otherwise.
412 */
413struct UsbRawRequest *UsbRawAllocRequest(const UsbRawHandle *devHandle, int32_t isoPackets, int32_t length);
414
415/**
416 * @brief Releases the previously allocated transfer request.
417 *
418 * @param request Indicates the pointer to the transfer request to release.
419 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
420 * otherwise.
421 */
422int32_t UsbRawFreeRequest(const struct UsbRawRequest *request);
423
424/**
425 * @brief Fills required information in a bulk transfer request.
426 *
427 * @param request Indicates the pointer to the request to send.
428 * @param devHandle Indicates the pointer to the device handle.
429 * @param fillRequestData Indicates the pointer to the request data to fill.
430 *
431 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
432 * otherwise.
433 */
434int32_t UsbRawFillBulkRequest(
435    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);
436
437/**
438 * @brief Fills required information in control transfer configuration packets.
439 *
440 * @param setup Indicates the pointer to the control information.
441 * @param requestData Indicates the pointer to the request data to fill.
442 *
443 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
444 * otherwise.
445 */
446int32_t UsbRawFillControlSetup(const unsigned char *setup, const struct UsbControlRequestData *requestData);
447
448/**
449 * @brief Fills required information in a control transfer request.
450 *
451 * @param request Indicates the pointer to the request to send.
452 * @param devHandle Indicates the pointer to the device handle.
453 * @param fillRequestData Indicates the pointer to the request data to fill.
454 *
455 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
456 * otherwise.
457 */
458int32_t UsbRawFillControlRequest(
459    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);
460
461/**
462 * @brief Fills required information in an interrupt transfer request.
463 *
464 * @param request Indicates the pointer to the request to send.
465 * @param devHandle Indicates the pointer to the device handle.
466 * @param fillRequestData Indicates the pointer to the request data to fill.
467 *
468 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
469 * otherwise.
470 */
471int32_t UsbRawFillInterruptRequest(
472    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);
473
474/**
475 * @brief Fills required information in an isochronous transfer request.
476 *
477 * @param request Indicates the pointer to the request to send.
478 * @param devHandle Indicates the pointer to the device handle.
479 * @param fillRequestData Indicates the pointer to the request data to fill.
480 *
481 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
482 * otherwise.
483 */
484int32_t UsbRawFillIsoRequest(
485    const struct UsbRawRequest *request, const UsbRawHandle *devHandle, const struct UsbRawFillRequestData *fillData);
486
487/**
488 * @brief Submits a transfer request.
489 *
490 * @param request Indicates the pointer to the request to submit.
491 *
492 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
493 * otherwise.
494 */
495int32_t UsbRawSubmitRequest(const struct UsbRawRequest *request);
496
497/**
498 * @brief Cancels a transfer request.
499 *
500 * @param request Indicates the pointer to the request to cancel.
501 *
502 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
503 * otherwise.
504 */
505int32_t UsbRawCancelRequest(const struct UsbRawRequest *request);
506
507/**
508 * @brief Defines the handle for a transfer request event.
509 *
510 * @param devHandle Indicates the pointer to the device handle.
511 *
512 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
513 * otherwise.
514 */
515int32_t UsbRawHandleRequests(const UsbRawHandle *devHandle);
516int32_t GetRawConfigDescriptor(
517    const UsbRawHandle *rawHandle, uint8_t configIndex, uint8_t *configDesc, uint32_t configDescLen);
518
519/**
520 * @brief Defines the handle for a control msg.
521 *
522 * @param devHandle Indicates the pointer to the device handle.
523 *
524 * @return Returns <b>0</b> if the operation is successful; returns a negative value defined in {@link HDF_STATUS}
525 * otherwise.
526 */
527int32_t UsbRawControlMsg(const UsbRawHandle * const devHandle, struct UsbControlRequestData *ctrlData);
528
529/**
530 * @brief Defines the handle for get usb speed information.
531 *
532 * @param devHandle Indicates the pointer to the device handle.
533 *
534 * @return Returns speed enum value defined in {@link UsbnetHostDeviceSpeed}
535 * otherwise.
536 */
537int32_t UsbRawGetUsbSpeed(const UsbRawHandle * const devHandle);
538
539#ifdef __cplusplus
540}
541#endif
542
543#endif /* USB_RAW_API_H */
544/** @} */
545