LCOV - code coverage report
Current view: top level - zephyr/drivers/usb - udc.h Coverage Total Hit
Test: new.info Lines: 82.2 % 107 88
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2021-2022 Nordic Semiconductor ASA
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief New USB device controller (UDC) driver API
      10              :  */
      11              : 
      12              : #ifndef ZEPHYR_INCLUDE_UDC_H
      13              : #define ZEPHYR_INCLUDE_UDC_H
      14              : 
      15              : #include <zephyr/kernel.h>
      16              : #include <zephyr/device.h>
      17              : #include <zephyr/drivers/usb/udc_buf.h>
      18              : #include <zephyr/sys/atomic.h>
      19              : #include <zephyr/usb/usb_ch9.h>
      20              : 
      21              : /**
      22              :  * @brief Maximum packet size of control endpoint supported by the controller.
      23              :  */
      24            0 : enum udc_mps0 {
      25              :         UDC_MPS0_8,
      26              :         UDC_MPS0_16,
      27              :         UDC_MPS0_32,
      28              :         UDC_MPS0_64,
      29              : };
      30              : 
      31              : /**
      32              :  * USB device controller capabilities
      33              :  *
      34              :  * This structure is mainly intended for the USB device stack.
      35              :  */
      36            1 : struct udc_device_caps {
      37              :         /** USB high speed capable controller */
      38            1 :         uint32_t hs : 1;
      39              :         /** Controller supports USB remote wakeup */
      40            1 :         uint32_t rwup : 1;
      41              :         /** Controller performs status OUT stage automatically */
      42            1 :         uint32_t out_ack : 1;
      43              :         /** Controller expects device address to be set before status stage */
      44            1 :         uint32_t addr_before_status : 1;
      45              :         /** Controller can detect the state change of USB supply VBUS.*/
      46            1 :         uint32_t can_detect_vbus : 1;
      47              :         /** Maximum packet size for control endpoint */
      48            1 :         enum udc_mps0 mps0 : 2;
      49              : };
      50              : 
      51              : /**
      52              :  * @brief USB device actual speed
      53              :  */
      54            1 : enum udc_bus_speed {
      55              :         /** Device is probably not connected */
      56              :         UDC_BUS_UNKNOWN,
      57              :         /** Device is connected to a full speed bus */
      58              :         UDC_BUS_SPEED_FS,
      59              :         /** Device is connected to a high speed bus  */
      60              :         UDC_BUS_SPEED_HS,
      61              :         /** Device is connected to a super speed bus */
      62              :         UDC_BUS_SPEED_SS,
      63              : };
      64              : 
      65              : /**
      66              :  * USB device controller endpoint capabilities
      67              :  */
      68            1 : struct udc_ep_caps {
      69              :         /** Maximum packet size of the endpoint buffer */
      70            1 :         uint32_t mps : 16;
      71              :         /** Control transfer capable endpoint (for completeness) */
      72            1 :         uint32_t control : 1;
      73              :         /** Interrupt transfer capable endpoint */
      74            1 :         uint32_t interrupt : 1;
      75              :         /** Bulk transfer capable endpoint */
      76            1 :         uint32_t bulk : 1;
      77              :         /** ISO transfer capable endpoint */
      78            1 :         uint32_t iso : 1;
      79              :         /** High-Bandwidth (interrupt or iso) capable endpoint */
      80            1 :         uint32_t high_bandwidth : 1;
      81              :         /** IN transfer capable endpoint */
      82            1 :         uint32_t in : 1;
      83              :         /** OUT transfer capable endpoint */
      84            1 :         uint32_t out : 1;
      85              : };
      86              : 
      87              : /**
      88              :  * USB device controller endpoint status
      89              :  */
      90            1 : struct udc_ep_stat {
      91              :         /** Endpoint is enabled */
      92            1 :         uint32_t enabled : 1;
      93              :         /** Endpoint is halted (returning STALL PID) */
      94            1 :         uint32_t halted : 1;
      95              :         /** Last submitted PID is DATA1 */
      96            1 :         uint32_t data1 : 1;
      97              :         /** If double buffering is supported, last used buffer is odd */
      98            1 :         uint32_t odd : 1;
      99              :         /** Endpoint is busy */
     100            1 :         uint32_t busy : 1;
     101              : };
     102              : 
     103              : /**
     104              :  * USB device controller endpoint configuration
     105              :  *
     106              :  * This structure is mandatory for configuration and management of endpoints.
     107              :  * It is not exposed to higher layer and is used only by internal part
     108              :  * of UDC API and driver.
     109              :  */
     110            1 : struct udc_ep_config {
     111              :         /** Endpoint requests FIFO */
     112            1 :         struct k_fifo fifo;
     113              :         /** Endpoint capabilities */
     114            1 :         struct udc_ep_caps caps;
     115              :         /** Endpoint status */
     116            1 :         struct udc_ep_stat stat;
     117              :         /** Endpoint address */
     118            1 :         uint8_t addr;
     119              :         /** Endpoint attributes */
     120            1 :         uint8_t attributes;
     121              :         /** Maximum packet size */
     122            1 :         uint16_t mps;
     123              :         /** Polling interval */
     124            1 :         uint8_t interval;
     125              : };
     126              : 
     127              : 
     128              : /**
     129              :  * @brief USB device controller event types
     130              :  */
     131            1 : enum udc_event_type {
     132              :         /** VBUS ready event. Signals that VBUS is in stable condition. */
     133              :         UDC_EVT_VBUS_READY,
     134              :         /** VBUS removed event. Signals that VBUS is below the valid range. */
     135              :         UDC_EVT_VBUS_REMOVED,
     136              :         /** Device resume event */
     137              :         UDC_EVT_RESUME,
     138              :         /** Device suspended event */
     139              :         UDC_EVT_SUSPEND,
     140              :         /** Port reset detected */
     141              :         UDC_EVT_RESET,
     142              :         /** Start of Frame event */
     143              :         UDC_EVT_SOF,
     144              :         /** Endpoint request result event */
     145              :         UDC_EVT_EP_REQUEST,
     146              :         /**
     147              :          * Non-correctable error event, requires attention from higher
     148              :          * levels or application.
     149              :          */
     150              :         UDC_EVT_ERROR,
     151              : };
     152              : 
     153              : /**
     154              :  * USB device controller event
     155              :  *
     156              :  * Common structure for all events that originate from
     157              :  * the UDC driver and are passed to higher layer using
     158              :  * message queue and a callback (udc_event_cb_t) provided
     159              :  * by higher layer during controller initialization (udc_init).
     160              :  */
     161            1 : struct udc_event {
     162              :         /** Event type */
     163            1 :         enum udc_event_type type;
     164              :         union {
     165              :                 /** Event value */
     166            1 :                 uint32_t value;
     167              :                 /** Event status value, if any */
     168            1 :                 int status;
     169              :                 /** Pointer to request used only for UDC_EVT_EP_REQUEST */
     170            1 :                 struct net_buf *buf;
     171            0 :         };
     172              :         /** Pointer to device struct */
     173            1 :         const struct device *dev;
     174              : };
     175              : 
     176              : /**
     177              :  * UDC endpoint buffer info
     178              :  *
     179              :  * This structure is mandatory for all UDC request.
     180              :  * It contains the meta data about the request and is stored in
     181              :  * user_data array of net_buf structure for each request.
     182              :  */
     183            1 : struct udc_buf_info {
     184              :         /** Endpoint to which request is associated */
     185            1 :         uint8_t ep;
     186              :         /** Flag marks setup transfer */
     187            1 :         unsigned int setup : 1;
     188              :         /** Flag marks data stage of setup transfer */
     189            1 :         unsigned int data : 1;
     190              :         /** Flag marks status stage of setup transfer */
     191            1 :         unsigned int status : 1;
     192              :         /** Flag marks ZLP at the end of a transfer */
     193            1 :         unsigned int zlp : 1;
     194              :         /** Flag marks request buffer claimed by the controller (TBD) */
     195            1 :         unsigned int claimed : 1;
     196              :         /** Flag marks request buffer is queued (TBD) */
     197            1 :         unsigned int queued : 1;
     198              :         /** Transfer owner (usually pointer to a class instance) */
     199            1 :         void *owner;
     200              :         /** Transfer result, 0 on success, other values on error */
     201            0 :         int err;
     202              : } __packed;
     203              : 
     204              : /**
     205              :  * @typedef udc_event_cb_t
     206              :  * @brief Callback to submit UDC event to higher layer.
     207              :  *
     208              :  * At the higher level, the event is to be inserted into a message queue.
     209              :  * (TBD) Maybe it is better to provide a pointer to k_msgq passed during
     210              :  * initialization.
     211              :  *
     212              :  * @param[in] dev      Pointer to device struct of the driver instance
     213              :  * @param[in] event    Point to event structure
     214              :  *
     215              :  * @return 0 on success, all other values should be treated as error.
     216              :  */
     217            1 : typedef int (*udc_event_cb_t)(const struct device *dev,
     218              :                               const struct udc_event *const event);
     219              : 
     220              : /**
     221              :  * @brief UDC driver API
     222              :  * This is the mandatory API any USB device controller driver needs to expose
     223              :  * with exception of:
     224              :  *   device_speed(), test_mode() are only required for HS controllers
     225              :  */
     226            1 : struct udc_api {
     227              :         enum udc_bus_speed (*device_speed)(const struct device *dev);
     228            0 :         int (*ep_enqueue)(const struct device *dev,
     229              :                           struct udc_ep_config *const cfg,
     230              :                           struct net_buf *const buf);
     231            0 :         int (*ep_dequeue)(const struct device *dev,
     232              :                           struct udc_ep_config *const cfg);
     233            0 :         int (*ep_set_halt)(const struct device *dev,
     234              :                            struct udc_ep_config *const cfg);
     235            0 :         int (*ep_clear_halt)(const struct device *dev,
     236              :                              struct udc_ep_config *const cfg);
     237            0 :         int (*ep_try_config)(const struct device *dev,
     238              :                              struct udc_ep_config *const cfg);
     239            0 :         int (*ep_enable)(const struct device *dev,
     240              :                          struct udc_ep_config *const cfg);
     241            0 :         int (*ep_disable)(const struct device *dev,
     242              :                           struct udc_ep_config *const cfg);
     243            0 :         int (*host_wakeup)(const struct device *dev);
     244            0 :         int (*set_address)(const struct device *dev,
     245              :                            const uint8_t addr);
     246            0 :         int (*test_mode)(const struct device *dev,
     247              :                          const uint8_t mode, const bool dryrun);
     248            0 :         int (*enable)(const struct device *dev);
     249            0 :         int (*disable)(const struct device *dev);
     250            0 :         int (*init)(const struct device *dev);
     251            0 :         int (*shutdown)(const struct device *dev);
     252            0 :         void (*lock)(const struct device *dev);
     253            0 :         void (*unlock)(const struct device *dev);
     254              : };
     255              : 
     256              : /**
     257              :  * Controller is initialized by udc_init() and can generate the VBUS events,
     258              :  * if capable, but shall not be recognizable by host.
     259              :  */
     260            1 : #define UDC_STATUS_INITIALIZED          0
     261              : /**
     262              :  * Controller is enabled and all API functions are available,
     263              :  * controller is recognizable by host.
     264              :  */
     265            1 : #define UDC_STATUS_ENABLED              1
     266              : /** Controller is suspended by the host */
     267            1 : #define UDC_STATUS_SUSPENDED            2
     268              : 
     269              : /**
     270              :  * Common UDC driver data structure
     271              :  *
     272              :  * Mandatory structure for each UDC controller driver.
     273              :  * To be implemented as device's private data (device->data).
     274              :  */
     275            1 : struct udc_data {
     276              :         /** LUT for endpoint management */
     277            1 :         struct udc_ep_config *ep_lut[32];
     278              :         /** Controller capabilities */
     279            1 :         struct udc_device_caps caps;
     280              :         /** Driver access mutex */
     281            1 :         struct k_mutex mutex;
     282              :         /** Callback to submit an UDC event to higher layer */
     283            1 :         udc_event_cb_t event_cb;
     284              :         /** Opaque pointer to store higher layer context */
     285            1 :         const void *event_ctx;
     286              :         /** USB device controller status */
     287            1 :         atomic_t status;
     288              :         /** Internal used Control Sequence Stage */
     289            1 :         int stage;
     290              :         /** Pointer to buffer containing setup packet */
     291            1 :         struct net_buf *setup;
     292              :         /** Driver private data */
     293            1 :         void *priv;
     294              : };
     295              : 
     296              : /**
     297              :  * @brief New USB device controller (UDC) driver API
     298              :  * @defgroup udc_api USB Device Controller
     299              :  * @ingroup usb_interfaces
     300              :  * @since 3.3
     301              :  * @version 0.1.0
     302              :  * @{
     303              :  */
     304              : 
     305              : /**
     306              :  * @brief Checks whether the controller is initialized.
     307              :  *
     308              :  * @param[in] dev      Pointer to device struct of the driver instance
     309              :  *
     310              :  * @return true if controller is initialized, false otherwise
     311              :  */
     312            1 : static inline bool udc_is_initialized(const struct device *dev)
     313              : {
     314              :         struct udc_data *data = (struct udc_data *)dev->data;
     315              : 
     316              :         return atomic_test_bit(&data->status, UDC_STATUS_INITIALIZED);
     317              : }
     318              : 
     319              : /**
     320              :  * @brief Checks whether the controller is enabled.
     321              :  *
     322              :  * @param[in] dev      Pointer to device struct of the driver instance
     323              :  *
     324              :  * @return true if controller is enabled, false otherwise
     325              :  */
     326            1 : static inline bool udc_is_enabled(const struct device *dev)
     327              : {
     328              :         struct udc_data *data = (struct udc_data *)dev->data;
     329              : 
     330              :         return atomic_test_bit(&data->status, UDC_STATUS_ENABLED);
     331              : }
     332              : 
     333              : /**
     334              :  * @brief Checks whether the controller is suspended.
     335              :  *
     336              :  * @param[in] dev      Pointer to device struct of the driver instance
     337              :  *
     338              :  * @return true if controller is suspended, false otherwise
     339              :  */
     340            1 : static inline bool udc_is_suspended(const struct device *dev)
     341              : {
     342              :         struct udc_data *data = (struct udc_data *)dev->data;
     343              : 
     344              :         return atomic_test_bit(&data->status, UDC_STATUS_SUSPENDED);
     345              : }
     346              : 
     347              : /**
     348              :  * @brief Initialize USB device controller
     349              :  *
     350              :  * Initialize USB device controller and control IN/OUT endpoint.
     351              :  * After initialization controller driver should be able to detect
     352              :  * power state of the bus and signal power state changes.
     353              :  *
     354              :  * @param[in] dev       Pointer to device struct of the driver instance
     355              :  * @param[in] event_cb  Event callback from the higher layer (USB device stack)
     356              :  * @param[in] event_ctx Opaque pointer to higher layer context
     357              :  *
     358              :  * @return 0 on success, all other values should be treated as error.
     359              :  * @retval -EINVAL on parameter error (no callback is passed)
     360              :  * @retval -EALREADY already initialized
     361              :  */
     362            1 : int udc_init(const struct device *dev,
     363              :              udc_event_cb_t event_cb, const void *const event_ctx);
     364              : 
     365              : /**
     366              :  * @brief Enable USB device controller
     367              :  *
     368              :  * Enable powered USB device controller and allow host to
     369              :  * recognize and enumerate the device.
     370              :  *
     371              :  * @param[in] dev    Pointer to device struct of the driver instance
     372              :  *
     373              :  * @return 0 on success, all other values should be treated as error.
     374              :  * @retval -EPERM controller is not initialized
     375              :  * @retval -EALREADY already enabled
     376              :  * @retval -ETIMEDOUT enable operation timed out
     377              :  */
     378            1 : int udc_enable(const struct device *dev);
     379              : 
     380              : /**
     381              :  * @brief Disable USB device controller
     382              :  *
     383              :  * Disable enabled USB device controller.
     384              :  * The driver should continue to detect power state changes.
     385              :  *
     386              :  * @param[in] dev    Pointer to device struct of the driver instance
     387              :  *
     388              :  * @return 0 on success, all other values should be treated as error.
     389              :  * @retval -EALREADY already disabled
     390              :  */
     391            1 : int udc_disable(const struct device *dev);
     392              : 
     393              : /**
     394              :  * @brief Poweroff USB device controller
     395              :  *
     396              :  * Shut down the controller completely to reduce energy consumption
     397              :  * or to change the role of the controller.
     398              :  *
     399              :  * @param[in] dev    Pointer to device struct of the driver instance
     400              :  *
     401              :  * @return 0 on success, all other values should be treated as error.
     402              :  * @retval -EALREADY controller is not initialized
     403              :  */
     404            1 : int udc_shutdown(const struct device *dev);
     405              : 
     406              : /**
     407              :  * @brief Get USB device controller capabilities
     408              :  *
     409              :  * Obtain the capabilities of the controller
     410              :  * such as full speed (FS), high speed (HS), and more.
     411              :  *
     412              :  * @param[in] dev    Pointer to device struct of the driver instance
     413              :  *
     414              :  * @return USB device controller capabilities.
     415              :  */
     416            1 : static inline struct udc_device_caps udc_caps(const struct device *dev)
     417              : {
     418              :         struct udc_data *data = (struct udc_data *)dev->data;
     419              : 
     420              :         return data->caps;
     421              : }
     422              : 
     423              : /**
     424              :  * @brief Get actual USB device speed
     425              :  *
     426              :  * The function should be called after the reset event to determine
     427              :  * the actual bus speed.
     428              :  *
     429              :  * @param[in] dev    Pointer to device struct of the driver instance
     430              :  *
     431              :  * @return USB device controller capabilities.
     432              :  */
     433            1 : enum udc_bus_speed udc_device_speed(const struct device *dev);
     434              : 
     435              : /**
     436              :  * @brief Set USB device address.
     437              :  *
     438              :  * Set address of enabled USB device.
     439              :  *
     440              :  * @param[in] dev    Pointer to device struct of the driver instance
     441              :  * @param[in] addr   USB device address
     442              :  *
     443              :  * @return 0 on success, all other values should be treated as error.
     444              :  * @retval -EPERM controller is not enabled (or not initialized)
     445              :  */
     446            1 : static inline int udc_set_address(const struct device *dev, const uint8_t addr)
     447              : {
     448              :         const struct udc_api *api = (const struct udc_api *)dev->api;
     449              :         int ret;
     450              : 
     451              :         if (!udc_is_enabled(dev)) {
     452              :                 return -EPERM;
     453              :         }
     454              : 
     455              :         api->lock(dev);
     456              :         ret = api->set_address(dev, addr);
     457              :         api->unlock(dev);
     458              : 
     459              :         return ret;
     460              : }
     461              : 
     462              : /**
     463              :  * @brief Enable Test Mode.
     464              :  *
     465              :  * For compliance testing, high-speed controllers must support test modes.
     466              :  * A particular test is enabled by a SetFeature(TEST_MODE) request.
     467              :  * To disable a test mode, device needs to be power cycled.
     468              :  *
     469              :  * @param[in] dev    Pointer to device struct of the driver instance
     470              :  * @param[in] mode   Test mode
     471              :  * @param[in] dryrun Verify that a particular mode can be enabled, but do not
     472              :  *                   enable test mode
     473              :  *
     474              :  * @return 0 on success, all other values should be treated as error.
     475              :  * @retval -ENOTSUP Test mode is not supported
     476              :  */
     477            1 : static inline int udc_test_mode(const struct device *dev,
     478              :                                 const uint8_t mode, const bool dryrun)
     479              : {
     480              :         const struct udc_api *api = (const struct udc_api *)dev->api;
     481              :         int ret;
     482              : 
     483              :         if (!udc_is_enabled(dev)) {
     484              :                 return -EPERM;
     485              :         }
     486              : 
     487              :         if (api->test_mode != NULL) {
     488              :                 api->lock(dev);
     489              :                 ret = api->test_mode(dev, mode, dryrun);
     490              :                 api->unlock(dev);
     491              :         } else {
     492              :                 ret = -ENOTSUP;
     493              :         }
     494              : 
     495              :         return ret;
     496              : }
     497              : 
     498              : /**
     499              :  * @brief Initiate host wakeup procedure.
     500              :  *
     501              :  * Initiate host wakeup. Only possible when the bus is suspended.
     502              :  *
     503              :  * @param[in] dev    Pointer to device struct of the driver instance
     504              :  *
     505              :  * @return 0 on success, all other values should be treated as error.
     506              :  * @retval -EPERM controller is not enabled (or not initialized)
     507              :  */
     508            1 : static inline int udc_host_wakeup(const struct device *dev)
     509              : {
     510              :         const struct udc_api *api = (const struct udc_api *)dev->api;
     511              :         int ret;
     512              : 
     513              :         if (!udc_is_enabled(dev)) {
     514              :                 return -EPERM;
     515              :         }
     516              : 
     517              :         api->lock(dev);
     518              :         ret = api->host_wakeup(dev);
     519              :         api->unlock(dev);
     520              : 
     521              :         return ret;
     522              : }
     523              : 
     524              : /**
     525              :  * @brief Try an endpoint configuration.
     526              :  *
     527              :  * Try an endpoint configuration based on endpoint descriptor.
     528              :  * This function may modify wMaxPacketSize descriptor fields
     529              :  * of the endpoint. All properties of the descriptor,
     530              :  * such as direction, and transfer type, should be set correctly.
     531              :  * If wMaxPacketSize value is zero, it will be
     532              :  * updated to maximum buffer size of the endpoint.
     533              :  *
     534              :  * @param[in] dev        Pointer to device struct of the driver instance
     535              :  * @param[in] ep         Endpoint address (same as bEndpointAddress)
     536              :  * @param[in] attributes Endpoint attributes (same as bmAttributes)
     537              :  * @param[in] mps        Maximum packet size (same as wMaxPacketSize)
     538              :  * @param[in] interval   Polling interval (same as bInterval)
     539              :  *
     540              :  * @return 0 on success, all other values should be treated as error.
     541              :  * @retval -EINVAL on wrong parameter
     542              :  * @retval -ENOTSUP endpoint configuration not supported
     543              :  * @retval -ENODEV no endpoints available
     544              :  */
     545            1 : int udc_ep_try_config(const struct device *dev,
     546              :                       const uint8_t ep,
     547              :                       const uint8_t attributes,
     548              :                       uint16_t *const mps,
     549              :                       const uint8_t interval);
     550              : 
     551              : /**
     552              :  * @brief Configure and enable endpoint.
     553              :  *
     554              :  * Configure and make an endpoint ready for use.
     555              :  * Valid for all endpoints except control IN/OUT.
     556              :  *
     557              :  * @param[in] dev        Pointer to device struct of the driver instance
     558              :  * @param[in] ep         Endpoint address (same as bEndpointAddress)
     559              :  * @param[in] attributes Endpoint attributes (same as bmAttributes)
     560              :  * @param[in] mps        Maximum packet size (same as wMaxPacketSize)
     561              :  * @param[in] interval   Polling interval (same as bInterval)
     562              :  *
     563              :  * @return 0 on success, all other values should be treated as error.
     564              :  * @retval -EINVAL on wrong parameter (control IN/OUT endpoint)
     565              :  * @retval -EPERM controller is not initialized
     566              :  * @retval -ENODEV endpoint configuration not found
     567              :  * @retval -EALREADY endpoint is already enabled
     568              :  */
     569            1 : int udc_ep_enable(const struct device *dev,
     570              :                   const uint8_t ep,
     571              :                   const uint8_t attributes,
     572              :                   const uint16_t mps,
     573              :                   const uint8_t interval);
     574              : 
     575              : /**
     576              :  * @brief Disable endpoint.
     577              :  *
     578              :  * Valid for all endpoints except control IN/OUT.
     579              :  *
     580              :  * @param[in] dev    Pointer to device struct of the driver instance
     581              :  * @param[in] ep     Endpoint address
     582              :  *
     583              :  * @return 0 on success, all other values should be treated as error.
     584              :  * @retval -EINVAL on wrong parameter (control IN/OUT endpoint)
     585              :  * @retval -ENODEV endpoint configuration not found
     586              :  * @retval -EALREADY endpoint is already disabled
     587              :  * @retval -EPERM controller is not initialized
     588              :  */
     589            1 : int udc_ep_disable(const struct device *dev, const uint8_t ep);
     590              : 
     591              : /**
     592              :  * @brief Halt endpoint
     593              :  *
     594              :  * Valid for all endpoints.
     595              :  *
     596              :  * @param[in] dev    Pointer to device struct of the driver instance
     597              :  * @param[in] ep     Endpoint address
     598              :  *
     599              :  * @return 0 on success, all other values should be treated as error.
     600              :  * @retval -ENODEV endpoint configuration not found
     601              :  * @retval -ENOTSUP not supported (e.g. isochronous endpoint)
     602              :  * @retval -EPERM controller is not enabled
     603              :  */
     604            1 : int udc_ep_set_halt(const struct device *dev, const uint8_t ep);
     605              : 
     606              : /**
     607              :  * @brief Clear endpoint halt
     608              :  *
     609              :  * Valid for all endpoints.
     610              :  *
     611              :  * @param[in] dev    Pointer to device struct of the driver instance
     612              :  * @param[in] ep     Endpoint address
     613              :  *
     614              :  * @return 0 on success, all other values should be treated as error.
     615              :  * @retval -ENODEV endpoint configuration not found
     616              :  * @retval -ENOTSUP not supported (e.g. isochronous endpoint)
     617              :  * @retval -EPERM controller is not enabled
     618              :  */
     619            1 : int udc_ep_clear_halt(const struct device *dev, const uint8_t ep);
     620              : 
     621              : /**
     622              :  * @brief Queue USB device controller request
     623              :  *
     624              :  * Add request to the queue. If the queue is empty, the request
     625              :  * buffer can be claimed by the controller immediately.
     626              :  *
     627              :  * @param[in] dev    Pointer to device struct of the driver instance
     628              :  * @param[in] buf    Pointer to UDC request buffer
     629              :  *
     630              :  * @return 0 on success, all other values should be treated as error.
     631              :  * @retval -ENODEV endpoint configuration not found
     632              :  * @retval -EACCES endpoint is not enabled (TBD)
     633              :  * @retval -EBUSY request can not be queued
     634              :  * @retval -EPERM controller is not initialized
     635              :  */
     636            1 : int udc_ep_enqueue(const struct device *dev, struct net_buf *const buf);
     637              : 
     638              : /**
     639              :  * @brief Remove all USB device controller requests from endpoint queue
     640              :  *
     641              :  * UDC_EVT_EP_REQUEST event will be generated when the driver
     642              :  * releases claimed buffer, no new requests will be claimed,
     643              :  * all requests in the queue will passed as chained list of
     644              :  * the event variable buf. The endpoint queue is empty after that.
     645              :  *
     646              :  * @param[in] dev    Pointer to device struct of the driver instance
     647              :  * @param[in] ep     Endpoint address
     648              :  *
     649              :  * @return 0 on success, all other values should be treated as error.
     650              :  * @retval -ENODEV endpoint configuration not found
     651              :  * @retval -EACCES endpoint is not disabled
     652              :  * @retval -EPERM controller is not initialized
     653              :  */
     654            1 : int udc_ep_dequeue(const struct device *dev, const uint8_t ep);
     655              : 
     656              : /**
     657              :  * @brief Allocate UDC request buffer
     658              :  *
     659              :  * Allocate a new buffer from common request buffer pool.
     660              :  *
     661              :  * @param[in] dev    Pointer to device struct of the driver instance
     662              :  * @param[in] ep     Endpoint address
     663              :  * @param[in] size   Size of the request buffer
     664              :  *
     665              :  * @return pointer to allocated request or NULL on error.
     666              :  */
     667            1 : struct net_buf *udc_ep_buf_alloc(const struct device *dev,
     668              :                                  const uint8_t ep,
     669              :                                  const size_t size);
     670              : 
     671              : /**
     672              :  * @brief Free UDC request buffer
     673              :  *
     674              :  * Put the buffer back into the request buffer pool.
     675              :  *
     676              :  * @param[in] dev    Pointer to device struct of the driver instance
     677              :  * @param[in] buf    Pointer to UDC request buffer
     678              :  *
     679              :  * @return 0 on success, all other values should be treated as error.
     680              :  */
     681            1 : int udc_ep_buf_free(const struct device *dev, struct net_buf *const buf);
     682              : 
     683              : /**
     684              :  * @brief Set ZLP flag in requests metadata.
     685              :  *
     686              :  * The controller should send a ZLP at the end of the transfer.
     687              :  *
     688              :  * @param[in] buf    Pointer to UDC request buffer
     689              :  */
     690            1 : static inline void udc_ep_buf_set_zlp(struct net_buf *const buf)
     691              : {
     692              :         struct udc_buf_info *bi;
     693              : 
     694              :         __ASSERT_NO_MSG(buf);
     695              :         bi = (struct udc_buf_info *)net_buf_user_data(buf);
     696              :         if (USB_EP_DIR_IS_IN(bi->ep)) {
     697              :                 bi->zlp = 1;
     698              :         }
     699              : }
     700              : 
     701              : /**
     702              :  * @brief Get requests metadata.
     703              :  *
     704              :  * @param[in] buf    Pointer to UDC request buffer
     705              :  *
     706              :  * @return pointer to metadata structure.
     707              :  */
     708            1 : static inline struct udc_buf_info *udc_get_buf_info(const struct net_buf *const buf)
     709              : {
     710              :         __ASSERT_NO_MSG(buf);
     711              :         return (struct udc_buf_info *)net_buf_user_data(buf);
     712              : }
     713              : 
     714              : 
     715              : /**
     716              :  * @brief Get pointer to higher layer context
     717              :  *
     718              :  * The address of the context is passed as an argument to the udc_init()
     719              :  * function and is stored in the UDC data.
     720              :  *
     721              :  * @param[in] dev Pointer to device struct of the driver instance
     722              :  *
     723              :  * @return Opaque pointer to higher layer context
     724              :  */
     725            1 : static inline const void *udc_get_event_ctx(const struct device *dev)
     726              : {
     727              :         struct udc_data *data = (struct udc_data *)dev->data;
     728              : 
     729              :         return data->event_ctx;
     730              : }
     731              : 
     732              : /**
     733              :  * @brief Get endpoint size from UDC endpoint configuration
     734              :  *
     735              :  * @param[in] cfg Pointer to UDC endpoint configuration
     736              :  *
     737              :  * @return Endpoint size
     738              :  */
     739            1 : static inline uint16_t udc_mps_ep_size(const struct udc_ep_config *const cfg)
     740              : {
     741              :         return USB_MPS_EP_SIZE(cfg->mps);
     742              : }
     743              : 
     744              : /**
     745              :  * @}
     746              :  */
     747              : 
     748              : #endif /* ZEPHYR_INCLUDE_UDC_H */
        

Generated by: LCOV version 2.0-1