Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
udc.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2021-2022 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
12#ifndef ZEPHYR_INCLUDE_UDC_H
13#define ZEPHYR_INCLUDE_UDC_H
14
15#include <zephyr/kernel.h>
16#include <zephyr/device.h>
18#include <zephyr/sys/atomic.h>
19#include <zephyr/usb/usb_ch9.h>
20
30
50
64
86
102
126
127
152
161struct udc_event {
164 union {
170 struct net_buf *buf;
171 };
173 const struct device *dev;
174};
175
187 unsigned int setup : 1;
189 unsigned int data : 1;
191 unsigned int status : 1;
193 unsigned int zlp : 1;
195 unsigned int claimed : 1;
197 unsigned int queued : 1;
199 void *owner;
201 int err;
202} __packed;
203
217typedef int (*udc_event_cb_t)(const struct device *dev,
218 const struct udc_event *const event);
219
226struct udc_api {
227 enum udc_bus_speed (*device_speed)(const struct device *dev);
228 int (*ep_enqueue)(const struct device *dev,
229 struct udc_ep_config *const cfg,
230 struct net_buf *const buf);
231 int (*ep_dequeue)(const struct device *dev,
232 struct udc_ep_config *const cfg);
233 int (*ep_set_halt)(const struct device *dev,
234 struct udc_ep_config *const cfg);
235 int (*ep_clear_halt)(const struct device *dev,
236 struct udc_ep_config *const cfg);
237 int (*ep_try_config)(const struct device *dev,
238 struct udc_ep_config *const cfg);
239 int (*ep_enable)(const struct device *dev,
240 struct udc_ep_config *const cfg);
241 int (*ep_disable)(const struct device *dev,
242 struct udc_ep_config *const cfg);
243 int (*host_wakeup)(const struct device *dev);
244 int (*set_address)(const struct device *dev,
245 const uint8_t addr);
246 int (*test_mode)(const struct device *dev,
247 const uint8_t mode, const bool dryrun);
248 int (*enable)(const struct device *dev);
249 int (*disable)(const struct device *dev);
250 int (*init)(const struct device *dev);
251 int (*shutdown)(const struct device *dev);
252 int (*lock)(const struct device *dev);
253 int (*unlock)(const struct device *dev);
254};
255
260#define UDC_STATUS_INITIALIZED 0
265#define UDC_STATUS_ENABLED 1
267#define UDC_STATUS_SUSPENDED 2
268
295
310static inline bool udc_is_initialized(const struct device *dev)
311{
312 struct udc_data *data = dev->data;
313
315}
316
324static inline bool udc_is_enabled(const struct device *dev)
325{
326 struct udc_data *data = dev->data;
327
329}
330
338static inline bool udc_is_suspended(const struct device *dev)
339{
340 struct udc_data *data = dev->data;
341
343}
344
360int udc_init(const struct device *dev,
361 udc_event_cb_t event_cb, const void *const event_ctx);
362
375int udc_enable(const struct device *dev);
376
388int udc_disable(const struct device *dev);
389
401int udc_shutdown(const struct device *dev);
402
413static inline struct udc_device_caps udc_caps(const struct device *dev)
414{
415 struct udc_data *data = dev->data;
416
417 return data->caps;
418}
419
430enum udc_bus_speed udc_device_speed(const struct device *dev);
431
443static inline int udc_set_address(const struct device *dev, const uint8_t addr)
444{
445 const struct udc_api *api = dev->api;
446 int ret;
447
448 if (!udc_is_enabled(dev)) {
449 return -EPERM;
450 }
451
452 api->lock(dev);
453 ret = api->set_address(dev, addr);
454 api->unlock(dev);
455
456 return ret;
457}
458
474static inline int udc_test_mode(const struct device *dev,
475 const uint8_t mode, const bool dryrun)
476{
477 const struct udc_api *api = dev->api;
478 int ret;
479
480 if (!udc_is_enabled(dev)) {
481 return -EPERM;
482 }
483
484 if (api->test_mode != NULL) {
485 api->lock(dev);
486 ret = api->test_mode(dev, mode, dryrun);
487 api->unlock(dev);
488 } else {
489 ret = -ENOTSUP;
490 }
491
492 return ret;
493}
494
505static inline int udc_host_wakeup(const struct device *dev)
506{
507 const struct udc_api *api = dev->api;
508 int ret;
509
510 if (!udc_is_enabled(dev)) {
511 return -EPERM;
512 }
513
514 api->lock(dev);
515 ret = api->host_wakeup(dev);
516 api->unlock(dev);
517
518 return ret;
519}
520
542int udc_ep_try_config(const struct device *dev,
543 const uint8_t ep,
544 const uint8_t attributes,
545 uint16_t *const mps,
546 const uint8_t interval);
547
566int udc_ep_enable(const struct device *dev,
567 const uint8_t ep,
568 const uint8_t attributes,
569 const uint16_t mps,
570 const uint8_t interval);
571
586int udc_ep_disable(const struct device *dev, const uint8_t ep);
587
601int udc_ep_set_halt(const struct device *dev, const uint8_t ep);
602
616int udc_ep_clear_halt(const struct device *dev, const uint8_t ep);
617
633int udc_ep_enqueue(const struct device *dev, struct net_buf *const buf);
634
651int udc_ep_dequeue(const struct device *dev, const uint8_t ep);
652
664struct net_buf *udc_ep_buf_alloc(const struct device *dev,
665 const uint8_t ep,
666 const size_t size);
667
678int udc_ep_buf_free(const struct device *dev, struct net_buf *const buf);
679
687static inline void udc_ep_buf_set_zlp(struct net_buf *const buf)
688{
689 struct udc_buf_info *bi;
690
691 __ASSERT_NO_MSG(buf);
692 bi = (struct udc_buf_info *)net_buf_user_data(buf);
693 if (USB_EP_DIR_IS_IN(bi->ep)) {
694 bi->zlp = 1;
695 }
696}
697
705static inline struct udc_buf_info *udc_get_buf_info(const struct net_buf *const buf)
706{
707 __ASSERT_NO_MSG(buf);
708 return (struct udc_buf_info *)net_buf_user_data(buf);
709}
710
711
722static inline const void *udc_get_event_ctx(const struct device *dev)
723{
724 struct udc_data *data = dev->data;
725
726 return data->event_ctx;
727}
728
736static inline uint16_t udc_mps_ep_size(const struct udc_ep_config *const cfg)
737{
738 return USB_MPS_EP_SIZE(cfg->mps);
739}
740
745#endif /* ZEPHYR_INCLUDE_UDC_H */
long atomic_t
Definition atomic_types.h:15
static bool atomic_test_bit(const atomic_t *target, int bit)
Atomically get and test a bit.
Definition atomic.h:127
static void * net_buf_user_data(const struct net_buf *buf)
Get a pointer to the user data of a buffer.
Definition net_buf.h:1576
#define ENOTSUP
Unsupported value.
Definition errno.h:114
#define EPERM
Not owner.
Definition errno.h:39
int udc_init(const struct device *dev, udc_event_cb_t event_cb, const void *const event_ctx)
Initialize USB device controller.
static struct udc_buf_info * udc_get_buf_info(const struct net_buf *const buf)
Get requests metadata.
Definition udc.h:705
static int udc_host_wakeup(const struct device *dev)
Initiate host wakeup procedure.
Definition udc.h:505
int udc_ep_set_halt(const struct device *dev, const uint8_t ep)
Halt endpoint.
static bool udc_is_enabled(const struct device *dev)
Checks whether the controller is enabled.
Definition udc.h:324
static const void * udc_get_event_ctx(const struct device *dev)
Get pointer to higher layer context.
Definition udc.h:722
static struct udc_device_caps udc_caps(const struct device *dev)
Get USB device controller capabilities.
Definition udc.h:413
static bool udc_is_initialized(const struct device *dev)
Checks whether the controller is initialized.
Definition udc.h:310
static void udc_ep_buf_set_zlp(struct net_buf *const buf)
Set ZLP flag in requests metadata.
Definition udc.h:687
int udc_ep_disable(const struct device *dev, const uint8_t ep)
Disable endpoint.
int udc_shutdown(const struct device *dev)
Poweroff USB device controller.
static uint16_t udc_mps_ep_size(const struct udc_ep_config *const cfg)
Get endpoint size from UDC endpoint configuration.
Definition udc.h:736
int udc_ep_dequeue(const struct device *dev, const uint8_t ep)
Remove all USB device controller requests from endpoint queue.
static int udc_set_address(const struct device *dev, const uint8_t addr)
Set USB device address.
Definition udc.h:443
static int udc_test_mode(const struct device *dev, const uint8_t mode, const bool dryrun)
Enable Test Mode.
Definition udc.h:474
int udc_ep_try_config(const struct device *dev, const uint8_t ep, const uint8_t attributes, uint16_t *const mps, const uint8_t interval)
Try an endpoint configuration.
static bool udc_is_suspended(const struct device *dev)
Checks whether the controller is suspended.
Definition udc.h:338
int udc_disable(const struct device *dev)
Disable USB device controller.
enum udc_bus_speed udc_device_speed(const struct device *dev)
Get actual USB device speed.
int udc_ep_enqueue(const struct device *dev, struct net_buf *const buf)
Queue USB device controller request.
int udc_ep_enable(const struct device *dev, const uint8_t ep, const uint8_t attributes, const uint16_t mps, const uint8_t interval)
Configure and enable endpoint.
struct net_buf * udc_ep_buf_alloc(const struct device *dev, const uint8_t ep, const size_t size)
Allocate UDC request buffer.
int udc_ep_clear_halt(const struct device *dev, const uint8_t ep)
Clear endpoint halt.
int udc_ep_buf_free(const struct device *dev, struct net_buf *const buf)
Free UDC request buffer.
int udc_enable(const struct device *dev)
Enable USB device controller.
Public kernel APIs.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Runtime device structure (in ROM) per driver instance.
Definition device.h:412
void * data
Address of the device instance private data.
Definition device.h:422
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:418
Definition kernel.h:2468
Mutex Structure.
Definition kernel.h:2994
Network buffer representation.
Definition net_buf.h:1006
uint16_t size
Amount of data that this buffer can store.
Definition net_buf.h:1038
Definition stat.h:57
UDC driver API This is the mandatory API any USB device controller driver needs to expose with except...
Definition udc.h:226
int(* init)(const struct device *dev)
Definition udc.h:250
int(* ep_dequeue)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:231
int(* ep_disable)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:241
int(* unlock)(const struct device *dev)
Definition udc.h:253
int(* ep_enable)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:239
int(* set_address)(const struct device *dev, const uint8_t addr)
Definition udc.h:244
int(* ep_try_config)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:237
int(* disable)(const struct device *dev)
Definition udc.h:249
int(* ep_clear_halt)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:235
int(* ep_enqueue)(const struct device *dev, struct udc_ep_config *const cfg, struct net_buf *const buf)
Definition udc.h:228
int(* test_mode)(const struct device *dev, const uint8_t mode, const bool dryrun)
Definition udc.h:246
int(* lock)(const struct device *dev)
Definition udc.h:252
int(* shutdown)(const struct device *dev)
Definition udc.h:251
int(* ep_set_halt)(const struct device *dev, struct udc_ep_config *const cfg)
Definition udc.h:233
enum udc_bus_speed(* device_speed)(const struct device *dev)
Definition udc.h:227
int(* host_wakeup)(const struct device *dev)
Definition udc.h:243
int(* enable)(const struct device *dev)
Definition udc.h:248
UDC endpoint buffer info.
Definition udc.h:183
uint8_t ep
Endpoint to which request is associated.
Definition udc.h:185
void * owner
Transfer owner (usually pointer to a class instance)
Definition udc.h:199
unsigned int queued
Flag marks request buffer is queued (TBD)
Definition udc.h:197
unsigned int status
Flag marks status stage of setup transfer.
Definition udc.h:191
unsigned int setup
Flag marks setup transfer.
Definition udc.h:187
unsigned int claimed
Flag marks request buffer claimed by the controller (TBD)
Definition udc.h:195
unsigned int data
Flag marks data stage of setup transfer.
Definition udc.h:189
int err
Transfer result, 0 on success, other values on error.
Definition udc.h:201
unsigned int zlp
Flag marks ZLP at the end of a transfer.
Definition udc.h:193
Common UDC driver data structure.
Definition udc.h:275
struct k_mutex mutex
Driver access mutex.
Definition udc.h:281
struct net_buf * setup
Pointer to buffer containing setup packet.
Definition udc.h:291
udc_event_cb_t event_cb
Callback to submit an UDC event to higher layer.
Definition udc.h:283
atomic_t status
USB device controller status.
Definition udc.h:287
struct udc_device_caps caps
Controller capabilities.
Definition udc.h:279
const void * event_ctx
Opaque pointer to store higher layer context.
Definition udc.h:285
int stage
Internal used Control Sequence Stage.
Definition udc.h:289
void * priv
Driver private data.
Definition udc.h:293
struct udc_ep_config * ep_lut[32]
LUT for endpoint management.
Definition udc.h:277
USB device controller capabilities.
Definition udc.h:36
uint32_t out_ack
Controller performs status OUT stage automatically.
Definition udc.h:42
enum udc_mps0 mps0
Maximum packet size for control endpoint.
Definition udc.h:48
uint32_t can_detect_vbus
Controller can detect the state change of USB supply VBUS.
Definition udc.h:46
uint32_t rwup
Controller supports USB remote wakeup.
Definition udc.h:40
uint32_t hs
USB high speed capable controller.
Definition udc.h:38
uint32_t addr_before_status
Controller expects device address to be set before status stage.
Definition udc.h:44
USB device controller endpoint capabilities.
Definition udc.h:68
uint32_t iso
ISO transfer capable endpoint.
Definition udc.h:78
uint32_t in
IN transfer capable endpoint.
Definition udc.h:82
uint32_t mps
Maximum packet size of the endpoint buffer.
Definition udc.h:70
uint32_t bulk
Bulk transfer capable endpoint.
Definition udc.h:76
uint32_t interrupt
Interrupt transfer capable endpoint.
Definition udc.h:74
uint32_t control
Control transfer capable endpoint (for completeness)
Definition udc.h:72
uint32_t high_bandwidth
High-Bandwidth (interrupt or iso) capable endpoint.
Definition udc.h:80
uint32_t out
OUT transfer capable endpoint.
Definition udc.h:84
USB device controller endpoint configuration.
Definition udc.h:110
uint8_t interval
Polling interval.
Definition udc.h:124
struct udc_ep_caps caps
Endpoint capabilities.
Definition udc.h:114
struct k_fifo fifo
Endpoint requests FIFO.
Definition udc.h:112
uint8_t addr
Endpoint address.
Definition udc.h:118
uint8_t attributes
Endpoint attributes.
Definition udc.h:120
uint16_t mps
Maximum packet size.
Definition udc.h:122
USB device controller endpoint status.
Definition udc.h:90
uint32_t odd
If double buffering is supported, last used buffer is odd.
Definition udc.h:98
uint32_t data1
Last submitted PID is DATA1.
Definition udc.h:96
uint32_t enabled
Endpoint is enabled.
Definition udc.h:92
uint32_t busy
Endpoint is busy.
Definition udc.h:100
uint32_t halted
Endpoint is halted (returning STALL PID)
Definition udc.h:94
USB device controller event.
Definition udc.h:161
int status
Event status value, if any.
Definition udc.h:168
enum udc_event_type type
Event type.
Definition udc.h:163
const struct device * dev
Pointer to device struct.
Definition udc.h:173
struct net_buf * buf
Pointer to request used only for UDC_EVT_EP_REQUEST.
Definition udc.h:170
uint32_t value
Event value.
Definition udc.h:166
udc_event_type
USB device controller event types.
Definition udc.h:131
@ UDC_EVT_VBUS_READY
VBUS ready event.
Definition udc.h:133
@ UDC_EVT_RESUME
Device resume event.
Definition udc.h:137
@ UDC_EVT_SUSPEND
Device suspended event.
Definition udc.h:139
@ UDC_EVT_VBUS_REMOVED
VBUS removed event.
Definition udc.h:135
@ UDC_EVT_EP_REQUEST
Endpoint request result event.
Definition udc.h:145
@ UDC_EVT_ERROR
Non-correctable error event, requires attention from higher levels or application.
Definition udc.h:150
@ UDC_EVT_RESET
Port reset detected.
Definition udc.h:141
@ UDC_EVT_SOF
Start of Frame event.
Definition udc.h:143
udc_bus_speed
USB device actual speed.
Definition udc.h:54
@ UDC_BUS_SPEED_SS
Device is connected to a super speed bus.
Definition udc.h:62
@ UDC_BUS_SPEED_FS
Device is connected to a full speed bus.
Definition udc.h:58
@ UDC_BUS_UNKNOWN
Device is probably not connected.
Definition udc.h:56
@ UDC_BUS_SPEED_HS
Device is connected to a high speed bus
Definition udc.h:60
#define UDC_STATUS_INITIALIZED
Controller is initialized by udc_init() and can generate the VBUS events, if capable,...
Definition udc.h:260
int(* udc_event_cb_t)(const struct device *dev, const struct udc_event *const event)
Callback to submit UDC event to higher layer.
Definition udc.h:217
udc_mps0
Maximum packet size of control endpoint supported by the controller.
Definition udc.h:24
@ UDC_MPS0_32
Definition udc.h:27
@ UDC_MPS0_16
Definition udc.h:26
@ UDC_MPS0_64
Definition udc.h:28
@ UDC_MPS0_8
Definition udc.h:25
#define UDC_STATUS_SUSPENDED
Controller is suspended by the host.
Definition udc.h:267
#define UDC_STATUS_ENABLED
Controller is enabled and all API functions are available, controller is recognizable by host.
Definition udc.h:265
Buffers for USB device support.
USB Chapter 9 structures and definitions.
#define USB_EP_DIR_IS_IN(ep)
True if the endpoint is an IN endpoint.
Definition usb_ch9.h:318
#define USB_MPS_EP_SIZE(mps)
Get endpoint size field from Max Packet Size value.
Definition usb_ch9.h:357