Zephyr API Documentation 4.0.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
usb_device.h
Go to the documentation of this file.
1/* SPDX-License-Identifier: BSD-3-Clause */
2
3/*
4 * LPCUSB, an USB device driver for LPC microcontrollers
5 * Copyright (C) 2006 Bertrik Sikken (bertrik@sikken.nl)
6 * Copyright (c) 2016 Intel Corporation
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 * 3. The name of the author may not be used to endorse or promote products
17 * derived from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
38#ifndef ZEPHYR_INCLUDE_USB_USB_DEVICE_H_
39#define ZEPHYR_INCLUDE_USB_USB_DEVICE_H_
40
42#include <zephyr/usb/usb_ch9.h>
43#include <zephyr/logging/log.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/*
51 * These macros should be used to place the USB descriptors
52 * in predetermined order in the RAM.
53 */
54#define USBD_DEVICE_DESCR_DEFINE(p) \
55 static __in_section(usb, descriptor_##p, 0) __used __aligned(1)
56#define USBD_CLASS_DESCR_DEFINE(p, instance) \
57 static __in_section(usb, descriptor_##p.1, instance) __used __aligned(1)
58#define USBD_MISC_DESCR_DEFINE(p) \
59 static __in_section(usb, descriptor_##p, 2) __used __aligned(1)
60#define USBD_USER_DESCR_DEFINE(p) \
61 static __in_section(usb, descriptor_##p, 3) __used __aligned(1)
62#define USBD_STRING_DESCR_DEFINE(p) \
63 static __in_section(usb, descriptor_##p, 4) __used __aligned(1)
64#define USBD_STRING_DESCR_USER_DEFINE(p) \
65 static __in_section(usb, descriptor_##p, 5) __used __aligned(1)
66#define USBD_TERM_DESCR_DEFINE(p) \
67 static __in_section(usb, descriptor_##p, 6) __used __aligned(1)
68
69/*
70 * This macro should be used to place the struct usb_cfg_data
71 * inside usb data section in the RAM.
72 */
73#define USBD_DEFINE_CFG_DATA(name) \
74 static STRUCT_SECTION_ITERABLE(usb_cfg_data, name)
75
76#define USBD_CFG_DATA_DEFINE(p, name) __DEPRECATED_MACRO \
77 static __in_section(_usb_cfg_data, static, p##_name) __used __aligned(4)
78
79/*************************************************************************
80 * USB configuration
81 **************************************************************************/
82
83#define USB_MAX_CTRL_MPS 64
84#define USB_MAX_FS_BULK_MPS 64
85#define USB_MAX_FS_INT_MPS 64
86#define USB_MAX_FS_ISO_MPS 1023
88/*************************************************************************
89 * USB application interface
90 **************************************************************************/
91
103typedef void (*usb_ep_callback)(uint8_t ep,
104 enum usb_dc_ep_cb_status_code cb_status);
105
117typedef int (*usb_request_handler)(struct usb_setup_packet *setup,
118 int32_t *transfer_len, uint8_t **payload_data);
119
123typedef void (*usb_interface_config)(struct usb_desc_header *head,
124 uint8_t bInterfaceNumber);
125
146
168
202
213int usb_set_config(const uint8_t *usb_descriptor);
214
222int usb_deconfig(void);
223
241
251int usb_disable(void);
252
269int usb_write(uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret);
270
288int usb_read(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes);
289
302
315
334int usb_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len,
335 uint32_t *read_bytes);
336
337
352
356typedef void (*usb_transfer_callback)(uint8_t ep, int tsize, void *priv);
357
358/* USB transfer flags */
359#define USB_TRANS_READ BIT(0)
360#define USB_TRANS_WRITE BIT(1)
361#define USB_TRANS_NO_ZLP BIT(2)
370
388int usb_transfer(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags,
389 usb_transfer_callback cb, void *priv);
390
407int usb_transfer_sync(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags);
408
416
421
431
443
450
455#define USB_DEVICE_BOS_DESC_DEFINE_CAP \
456 static __in_section(usb, bos_desc_area, 1) __aligned(1) __used
457
466void usb_bos_register_cap(void *hdr);
467
472#ifdef __cplusplus
473}
474#endif
475
476#endif /* ZEPHYR_INCLUDE_USB_USB_DEVICE_H_ */
void(* usb_dc_status_callback)(enum usb_dc_status_code cb_status, const uint8_t *param)
Callback function signature for the device.
Definition usb_dc.h:135
usb_dc_status_code
USB Driver Status Codes.
Definition usb_dc.h:35
usb_dc_ep_cb_status_code
USB Endpoint Callback Status Codes.
Definition usb_dc.h:67
int usb_transfer_sync(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags)
Start a transfer and block-wait for completion.
void usb_bos_register_cap(void *hdr)
Register BOS capability descriptor.
int usb_transfer(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags, usb_transfer_callback cb, void *priv)
Start a transfer.
int usb_set_config(const uint8_t *usb_descriptor)
Configure USB controller.
int usb_deconfig(void)
Deconfigure USB controller.
void(* usb_transfer_callback)(uint8_t ep, int tsize, void *priv)
Callback function signature for transfer completion.
Definition usb_device.h:356
void(* usb_interface_config)(struct usb_desc_header *head, uint8_t bInterfaceNumber)
Function for interface runtime configuration.
Definition usb_device.h:123
void usb_transfer_ep_callback(uint8_t ep, enum usb_dc_ep_cb_status_code)
Transfer management endpoint callback.
int usb_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes)
Read data from the specified endpoint.
bool usb_get_remote_wakeup_status(void)
Get status of the USB remote wakeup feature.
bool usb_transfer_is_busy(uint8_t ep)
Check that transfer is ongoing for the endpoint.
int usb_disable(void)
Disable the USB device.
int usb_write(uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret)
Write data to the specified endpoint.
void usb_cancel_transfers(void)
Cancel all ongoing transfers.
int usb_wakeup_request(void)
Start the USB remote wakeup procedure.
void(* usb_ep_callback)(uint8_t ep, enum usb_dc_ep_cb_status_code cb_status)
Callback function signature for the USB Endpoint status.
Definition usb_device.h:103
int usb_ep_read_continue(uint8_t ep)
Continue reading data from the endpoint.
int usb_ep_set_stall(uint8_t ep)
Set STALL condition on the specified endpoint.
int usb_read(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes)
Read data from the specified endpoint.
void usb_cancel_transfer(uint8_t ep)
Cancel any ongoing transfer on the specified endpoint.
int usb_enable(usb_dc_status_callback status_cb)
Enable the USB subsystem and associated hardware.
int(* usb_request_handler)(struct usb_setup_packet *setup, int32_t *transfer_len, uint8_t **payload_data)
Callback function signature for class specific requests.
Definition usb_device.h:117
int usb_ep_clear_stall(uint8_t ep)
Clears STALL condition on the specified endpoint.
flags
Definition parser.h:96
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__INT32_TYPE__ int32_t
Definition stdint.h:74
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
USB device configuration.
Definition usb_device.h:177
usb_interface_config interface_config
Function for interface runtime configuration.
Definition usb_device.h:186
uint8_t num_endpoints
Number of individual endpoints in the device configuration.
Definition usb_device.h:194
const uint8_t * usb_device_description
USB device description, see http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors.
Definition usb_device.h:182
struct usb_interface_cfg_data interface
USB interface (Class) handler and storage space.
Definition usb_device.h:192
void(* cb_usb_status)(struct usb_cfg_data *cfg, enum usb_dc_status_code cb_status, const uint8_t *param)
Callback to be notified on USB connection status change.
Definition usb_device.h:188
struct usb_ep_cfg_data * endpoint
Pointer to an array of endpoint structs of length equal to the number of EP associated with the devic...
Definition usb_device.h:200
void * interface_descriptor
Pointer to interface descriptor.
Definition usb_device.h:184
Header of an USB descriptor.
Definition usb_ch9.h:144
USB Endpoint Configuration.
Definition usb_device.h:131
usb_ep_callback ep_cb
Callback function for notification of data received and available to application or transmit done,...
Definition usb_device.h:137
uint8_t ep_addr
The number associated with the EP in the device configuration structure IN EP = 0x80 | <endpoint numb...
Definition usb_device.h:144
USB Interface Configuration.
Definition usb_device.h:152
usb_request_handler custom_handler
The custom request handler gets a first chance at handling the request before it is handed over to th...
Definition usb_device.h:166
usb_request_handler class_handler
Handler for USB Class specific Control (EP 0) communications.
Definition usb_device.h:154
usb_request_handler vendor_handler
Handler for USB Vendor specific commands.
Definition usb_device.h:156
USB Setup Data packet defined in spec.
Definition usb_ch9.h:40
USB Chapter 9 structures and definitions.
USB device controller APIs.