LCOV - code coverage report
Current view: top level - zephyr/drivers/usb - usb_dc.h Hit Total Coverage
Test: new.info Lines: 32 32 100.0 %
Date: 2024-12-21 18:13:37

          Line data    Source code
       1           1 : /* usb_dc.h - USB device controller driver interface */
       2             : 
       3             : /*
       4             :  * Copyright (c) 2016 Intel Corporation.
       5             :  *
       6             :  * SPDX-License-Identifier: Apache-2.0
       7             :  */
       8             : 
       9             : /**
      10             :  * @file
      11             :  * @brief USB device controller APIs
      12             :  *
      13             :  * This file contains the USB device controller APIs. All device controller
      14             :  * drivers should implement the APIs described in this file.
      15             :  */
      16             : 
      17             : #ifndef ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_
      18             : #define ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_
      19             : 
      20             : #include <zephyr/device.h>
      21             : 
      22             : /**
      23             :  * @brief USB Device Controller API
      24             :  * @defgroup _usb_device_controller_api USB Device Controller API
      25             :  * @since 1.5
      26             :  * @version 1.0.0
      27             :  * @{
      28             :  */
      29             : 
      30             : /**
      31             :  * @brief USB Driver Status Codes
      32             :  *
      33             :  * Status codes reported by the registered device status callback.
      34             :  */
      35           1 : enum usb_dc_status_code {
      36             :         /** USB error reported by the controller */
      37             :         USB_DC_ERROR,
      38             :         /** USB reset */
      39             :         USB_DC_RESET,
      40             :         /** USB connection established, hardware enumeration is completed */
      41             :         USB_DC_CONNECTED,
      42             :         /** USB configuration done */
      43             :         USB_DC_CONFIGURED,
      44             :         /** USB connection lost */
      45             :         USB_DC_DISCONNECTED,
      46             :         /** USB connection suspended by the HOST */
      47             :         USB_DC_SUSPEND,
      48             :         /** USB connection resumed by the HOST */
      49             :         USB_DC_RESUME,
      50             :         /** USB interface selected */
      51             :         USB_DC_INTERFACE,
      52             :         /** Set Feature ENDPOINT_HALT received */
      53             :         USB_DC_SET_HALT,
      54             :         /** Clear Feature ENDPOINT_HALT received */
      55             :         USB_DC_CLEAR_HALT,
      56             :         /** Start of Frame received */
      57             :         USB_DC_SOF,
      58             :         /** Initial USB connection status */
      59             :         USB_DC_UNKNOWN
      60             : };
      61             : 
      62             : /**
      63             :  * @brief USB Endpoint Callback Status Codes
      64             :  *
      65             :  * Status Codes reported by the registered endpoint callback.
      66             :  */
      67           1 : enum usb_dc_ep_cb_status_code {
      68             :         /** SETUP received */
      69             :         USB_DC_EP_SETUP,
      70             :         /** Out transaction on this EP, data is available for read */
      71             :         USB_DC_EP_DATA_OUT,
      72             :         /** In transaction done on this EP */
      73             :         USB_DC_EP_DATA_IN
      74             : };
      75             : 
      76             : /**
      77             :  * @brief USB Endpoint Transfer Type
      78             :  */
      79           1 : enum usb_dc_ep_transfer_type {
      80             :         /** Control type endpoint */
      81             :         USB_DC_EP_CONTROL = 0,
      82             :         /** Isochronous type endpoint */
      83             :         USB_DC_EP_ISOCHRONOUS,
      84             :         /** Bulk type endpoint */
      85             :         USB_DC_EP_BULK,
      86             :         /** Interrupt type endpoint  */
      87             :         USB_DC_EP_INTERRUPT
      88             : };
      89             : 
      90             : /**
      91             :  * @brief USB Endpoint Synchronization Type
      92             :  *
      93             :  * @note Valid only for Isochronous Endpoints
      94             :  */
      95           1 : enum usb_dc_ep_synchronozation_type {
      96             :         /** No Synchronization */
      97             :         USB_DC_EP_NO_SYNCHRONIZATION = (0U << 2U),
      98             :         /** Asynchronous */
      99             :         USB_DC_EP_ASYNCHRONOUS = (1U << 2U),
     100             :         /** Adaptive */
     101             :         USB_DC_EP_ADAPTIVE = (2U << 2U),
     102             :         /** Synchronous*/
     103             :         USB_DC_EP_SYNCHRONOUS = (3U << 2U)
     104             : };
     105             : 
     106             : /**
     107             :  * @brief USB Endpoint Configuration.
     108             :  *
     109             :  * Structure containing the USB endpoint configuration.
     110             :  */
     111           1 : struct usb_dc_ep_cfg_data {
     112             :         /** The number associated with the EP in the device
     113             :          *  configuration structure
     114             :          *       IN  EP = 0x80 | \<endpoint number\>
     115             :          *       OUT EP = 0x00 | \<endpoint number\>
     116             :          */
     117           1 :         uint8_t ep_addr;
     118             :         /** Endpoint max packet size */
     119           1 :         uint16_t ep_mps;
     120             :         /** Endpoint Transfer Type.
     121             :          * May be Bulk, Interrupt, Control or Isochronous
     122             :          */
     123           1 :         enum usb_dc_ep_transfer_type ep_type;
     124             : };
     125             : 
     126             : /**
     127             :  * Callback function signature for the USB Endpoint status
     128             :  */
     129           1 : typedef void (*usb_dc_ep_callback)(uint8_t ep,
     130             :                                    enum usb_dc_ep_cb_status_code cb_status);
     131             : 
     132             : /**
     133             :  * Callback function signature for the device
     134             :  */
     135           1 : typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status,
     136             :                                        const uint8_t *param);
     137             : 
     138             : /**
     139             :  * @brief Attach USB for device connection
     140             :  *
     141             :  * Function to attach USB for device connection. Upon success, the USB PLL
     142             :  * is enabled, and the USB device is now capable of transmitting and receiving
     143             :  * on the USB bus and of generating interrupts.
     144             :  *
     145             :  * @return 0 on success, negative errno code on fail.
     146             :  */
     147           1 : int usb_dc_attach(void);
     148             : 
     149             : /**
     150             :  * @brief Detach the USB device
     151             :  *
     152             :  * Function to detach the USB device. Upon success, the USB hardware PLL
     153             :  * is powered down and USB communication is disabled.
     154             :  *
     155             :  * @return 0 on success, negative errno code on fail.
     156             :  */
     157           1 : int usb_dc_detach(void);
     158             : 
     159             : /**
     160             :  * @brief Reset the USB device
     161             :  *
     162             :  * This function returns the USB device and firmware back to it's initial state.
     163             :  * N.B. the USB PLL is handled by the usb_detach function
     164             :  *
     165             :  * @return 0 on success, negative errno code on fail.
     166             :  */
     167           1 : int usb_dc_reset(void);
     168             : 
     169             : /**
     170             :  * @brief Set USB device address
     171             :  *
     172             :  * @param[in] addr Device address
     173             :  *
     174             :  * @return 0 on success, negative errno code on fail.
     175             :  */
     176           1 : int usb_dc_set_address(const uint8_t addr);
     177             : 
     178             : /**
     179             :  * @brief Set USB device controller status callback
     180             :  *
     181             :  * Function to set USB device controller status callback. The registered
     182             :  * callback is used to report changes in the status of the device controller.
     183             :  * The status code are described by the usb_dc_status_code enumeration.
     184             :  *
     185             :  * @param[in] cb Callback function
     186             :  */
     187           1 : void usb_dc_set_status_callback(const usb_dc_status_callback cb);
     188             : 
     189             : /**
     190             :  * @brief check endpoint capabilities
     191             :  *
     192             :  * Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure
     193             :  * provides the endpoint configuration parameters: endpoint address,
     194             :  * endpoint maximum packet size and endpoint type.
     195             :  * The driver should check endpoint capabilities and return 0 if the
     196             :  * endpoint configuration is possible.
     197             :  *
     198             :  * @param[in] cfg Endpoint config
     199             :  *
     200             :  * @return 0 on success, negative errno code on fail.
     201             :  */
     202           1 : int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data * const cfg);
     203             : 
     204             : /**
     205             :  * @brief Configure endpoint
     206             :  *
     207             :  * Function to configure an endpoint. usb_dc_ep_cfg_data structure provides
     208             :  * the endpoint configuration parameters: endpoint address, endpoint maximum
     209             :  * packet size and endpoint type.
     210             :  *
     211             :  * @param[in] cfg Endpoint config
     212             :  *
     213             :  * @return 0 on success, negative errno code on fail.
     214             :  */
     215           1 : int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data * const cfg);
     216             : 
     217             : /**
     218             :  * @brief Set stall condition for the selected endpoint
     219             :  *
     220             :  * @param[in] ep Endpoint address corresponding to the one
     221             :  *               listed in the device configuration table
     222             :  *
     223             :  * @return 0 on success, negative errno code on fail.
     224             :  */
     225           1 : int usb_dc_ep_set_stall(const uint8_t ep);
     226             : 
     227             : /**
     228             :  * @brief Clear stall condition for the selected endpoint
     229             :  *
     230             :  * @param[in] ep Endpoint address corresponding to the one
     231             :  *               listed in the device configuration table
     232             :  *
     233             :  * @return 0 on success, negative errno code on fail.
     234             :  */
     235           1 : int usb_dc_ep_clear_stall(const uint8_t ep);
     236             : 
     237             : /**
     238             :  * @brief Check if the selected endpoint is stalled
     239             :  *
     240             :  * @param[in]  ep       Endpoint address corresponding to the one
     241             :  *                      listed in the device configuration table
     242             :  * @param[out] stalled  Endpoint stall status
     243             :  *
     244             :  * @return 0 on success, negative errno code on fail.
     245             :  */
     246           1 : int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled);
     247             : 
     248             : /**
     249             :  * @brief Halt the selected endpoint
     250             :  *
     251             :  * @param[in] ep Endpoint address corresponding to the one
     252             :  *               listed in the device configuration table
     253             :  *
     254             :  * @return 0 on success, negative errno code on fail.
     255             :  */
     256           1 : int usb_dc_ep_halt(const uint8_t ep);
     257             : 
     258             : /**
     259             :  * @brief Enable the selected endpoint
     260             :  *
     261             :  * Function to enable the selected endpoint. Upon success interrupts are
     262             :  * enabled for the corresponding endpoint and the endpoint is ready for
     263             :  * transmitting/receiving data.
     264             :  *
     265             :  * @param[in] ep Endpoint address corresponding to the one
     266             :  *               listed in the device configuration table
     267             :  *
     268             :  * @return 0 on success, negative errno code on fail.
     269             :  */
     270           1 : int usb_dc_ep_enable(const uint8_t ep);
     271             : 
     272             : /**
     273             :  * @brief Disable the selected endpoint
     274             :  *
     275             :  * Function to disable the selected endpoint. Upon success interrupts are
     276             :  * disabled for the corresponding endpoint and the endpoint is no longer able
     277             :  * for transmitting/receiving data.
     278             :  *
     279             :  * @param[in] ep Endpoint address corresponding to the one
     280             :  *               listed in the device configuration table
     281             :  *
     282             :  * @return 0 on success, negative errno code on fail.
     283             :  */
     284           1 : int usb_dc_ep_disable(const uint8_t ep);
     285             : 
     286             : /**
     287             :  * @brief Flush the selected endpoint
     288             :  *
     289             :  * This function flushes the FIFOs for the selected endpoint.
     290             :  *
     291             :  * @param[in] ep Endpoint address corresponding to the one
     292             :  *               listed in the device configuration table
     293             :  *
     294             :  * @return 0 on success, negative errno code on fail.
     295             :  */
     296           1 : int usb_dc_ep_flush(const uint8_t ep);
     297             : 
     298             : /**
     299             :  * @brief Write data to the specified endpoint
     300             :  *
     301             :  * This function is called to write data to the specified endpoint. The
     302             :  * supplied usb_ep_callback function will be called when data is transmitted
     303             :  * out.
     304             :  *
     305             :  * @param[in]  ep        Endpoint address corresponding to the one
     306             :  *                       listed in the device configuration table
     307             :  * @param[in]  data      Pointer to data to write
     308             :  * @param[in]  data_len  Length of the data requested to write. This may
     309             :  *                       be zero for a zero length status packet.
     310             :  * @param[out] ret_bytes Bytes scheduled for transmission. This value
     311             :  *                       may be NULL if the application expects all
     312             :  *                       bytes to be written
     313             :  *
     314             :  * @return 0 on success, negative errno code on fail.
     315             :  */
     316           1 : int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data,
     317             :                     const uint32_t data_len, uint32_t * const ret_bytes);
     318             : 
     319             : /**
     320             :  * @brief Read data from the specified endpoint
     321             :  *
     322             :  * This function is called by the endpoint handler function, after an OUT
     323             :  * interrupt has been received for that EP. The application must only call this
     324             :  * function through the supplied usb_ep_callback function. This function clears
     325             :  * the ENDPOINT NAK, if all data in the endpoint FIFO has been read,
     326             :  * so as to accept more data from host.
     327             :  *
     328             :  * @param[in]  ep           Endpoint address corresponding to the one
     329             :  *                          listed in the device configuration table
     330             :  * @param[in]  data         Pointer to data buffer to write to
     331             :  * @param[in]  max_data_len Max length of data to read
     332             :  * @param[out] read_bytes   Number of bytes read. If data is NULL and
     333             :  *                          max_data_len is 0 the number of bytes
     334             :  *                          available for read should be returned.
     335             :  *
     336             :  * @return 0 on success, negative errno code on fail.
     337             :  */
     338           1 : int usb_dc_ep_read(const uint8_t ep, uint8_t *const data,
     339             :                    const uint32_t max_data_len, uint32_t *const read_bytes);
     340             : 
     341             : /**
     342             :  * @brief Set callback function for the specified endpoint
     343             :  *
     344             :  * Function to set callback function for notification of data received and
     345             :  * available to application or transmit done on the selected endpoint,
     346             :  * NULL if callback not required by application code. The callback status
     347             :  * code is described by usb_dc_ep_cb_status_code.
     348             :  *
     349             :  * @param[in] ep Endpoint address corresponding to the one
     350             :  *               listed in the device configuration table
     351             :  * @param[in] cb Callback function
     352             :  *
     353             :  * @return 0 on success, negative errno code on fail.
     354             :  */
     355           1 : int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb);
     356             : 
     357             : /**
     358             :  * @brief Read data from the specified endpoint
     359             :  *
     360             :  * This is similar to usb_dc_ep_read, the difference being that, it doesn't
     361             :  * clear the endpoint NAKs so that the consumer is not bogged down by further
     362             :  * upcalls till he is done with the processing of the data. The caller should
     363             :  * reactivate ep by invoking usb_dc_ep_read_continue() do so.
     364             :  *
     365             :  * @param[in]  ep           Endpoint address corresponding to the one
     366             :  *                          listed in the device configuration table
     367             :  * @param[in]  data         Pointer to data buffer to write to
     368             :  * @param[in]  max_data_len Max length of data to read
     369             :  * @param[out] read_bytes   Number of bytes read. If data is NULL and
     370             :  *                          max_data_len is 0 the number of bytes
     371             :  *                          available for read should be returned.
     372             :  *
     373             :  * @return 0 on success, negative errno code on fail.
     374             :  */
     375           1 : int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len,
     376             :                         uint32_t *read_bytes);
     377             : 
     378             : /**
     379             :  * @brief Continue reading data from the endpoint
     380             :  *
     381             :  * Clear the endpoint NAK and enable the endpoint to accept more data
     382             :  * from the host. Usually called after usb_dc_ep_read_wait() when the consumer
     383             :  * is fine to accept more data. Thus these calls together act as a flow control
     384             :  * mechanism.
     385             :  *
     386             :  * @param[in]  ep           Endpoint address corresponding to the one
     387             :  *                          listed in the device configuration table
     388             :  *
     389             :  * @return 0 on success, negative errno code on fail.
     390             :  */
     391           1 : int usb_dc_ep_read_continue(uint8_t ep);
     392             : 
     393             : /**
     394             :  * @brief Get endpoint max packet size
     395             :  *
     396             :  * @param[in]  ep           Endpoint address corresponding to the one
     397             :  *                          listed in the device configuration table
     398             :  *
     399             :  * @return Endpoint max packet size (mps)
     400             :  */
     401           1 : int usb_dc_ep_mps(uint8_t ep);
     402             : 
     403             : /**
     404             :  * @brief Start the host wake up procedure.
     405             :  *
     406             :  * Function to wake up the host if it's currently in sleep mode.
     407             :  *
     408             :  * @return 0 on success, negative errno code on fail.
     409             :  */
     410           1 : int usb_dc_wakeup_request(void);
     411             : 
     412             : /**
     413             :  * @}
     414             :  */
     415             : 
     416             : #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ */

Generated by: LCOV version 1.14