Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2022 Nordic Semiconductor ASA
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief New experimental USB device stack APIs and structures
      10             :  *
      11             :  * This file contains the USB device stack APIs and structures.
      12             :  */
      13             : 
      14             : #ifndef ZEPHYR_INCLUDE_USBH_H_
      15             : #define ZEPHYR_INCLUDE_USBH_H_
      16             : 
      17             : #include <stdint.h>
      18             : #include <zephyr/device.h>
      19             : #include <zephyr/net_buf.h>
      20             : #include <zephyr/sys/dlist.h>
      21             : #include <zephyr/drivers/usb/uhc.h>
      22             : #include <zephyr/sys/iterable_sections.h>
      23             : 
      24             : #ifdef __cplusplus
      25             : extern "C" {
      26             : #endif
      27             : 
      28             : /**
      29             :  * @brief USB HOST Core Layer API
      30             :  * @defgroup usb_host_core_api USB Host Core API
      31             :  * @ingroup usb
      32             :  * @{
      33             :  */
      34             : 
      35             : /**
      36             :  * USB host support runtime context
      37             :  */
      38           1 : struct usbh_contex {
      39             :         /** Name of the USB device */
      40           1 :         const char *name;
      41             :         /** Access mutex */
      42           1 :         struct k_mutex mutex;
      43             :         /** Pointer to UHC device struct */
      44           1 :         const struct device *dev;
      45             :         /** peripheral list */
      46           1 :         sys_dlist_t peripherals;
      47             : };
      48             : 
      49           0 : #define USBH_CONTROLLER_DEFINE(device_name, uhc_dev)                    \
      50             :         static STRUCT_SECTION_ITERABLE(usbh_contex, device_name) = {    \
      51             :                 .name = STRINGIFY(device_name),                         \
      52             :                 .mutex = Z_MUTEX_INITIALIZER(device_name.mutex),        \
      53             :                 .dev = uhc_dev,                                         \
      54             :         }
      55             : 
      56             : /**
      57             :  * @brief USB Class Code triple
      58             :  */
      59           1 : struct usbh_code_triple {
      60             :         /** Device Class Code */
      61           1 :         uint8_t dclass;
      62             :         /** Class Subclass Code */
      63           1 :         uint8_t sub;
      64             :         /** Class Protocol Code */
      65           1 :         uint8_t proto;
      66             : };
      67             : 
      68             : /**
      69             :  * @brief USB host class data and class instance API
      70             :  */
      71           1 : struct usbh_class_data {
      72             :         /** Class code supported by this instance */
      73           1 :         struct usbh_code_triple code;
      74             : 
      75             :         /** Initialization of the class implementation */
      76             :         /* int (*init)(struct usbh_contex *const uhs_ctx); */
      77             :         /** Request completion event handler */
      78           1 :         int (*request)(struct usbh_contex *const uhs_ctx,
      79             :                         struct uhc_transfer *const xfer, int err);
      80             :         /** Device connected handler  */
      81           1 :         int (*connected)(struct usbh_contex *const uhs_ctx);
      82             :         /** Device removed handler  */
      83           1 :         int (*removed)(struct usbh_contex *const uhs_ctx);
      84             :         /** Bus remote wakeup handler  */
      85           1 :         int (*rwup)(struct usbh_contex *const uhs_ctx);
      86             :         /** Bus suspended handler  */
      87           1 :         int (*suspended)(struct usbh_contex *const uhs_ctx);
      88             :         /** Bus resumed handler  */
      89           1 :         int (*resumed)(struct usbh_contex *const uhs_ctx);
      90             : };
      91             : 
      92             : /**
      93             :  */
      94           0 : #define USBH_DEFINE_CLASS(name) \
      95             :         static STRUCT_SECTION_ITERABLE(usbh_class_data, name)
      96             : 
      97             : 
      98             : /**
      99             :  * @brief Initialize the USB host support;
     100             :  *
     101             :  * @param[in] uhs_ctx Pointer to USB host support context
     102             :  *
     103             :  * @return 0 on success, other values on fail.
     104             :  */
     105           1 : int usbh_init(struct usbh_contex *uhs_ctx);
     106             : 
     107             : /**
     108             :  * @brief Enable the USB host support and class instances
     109             :  *
     110             :  * This function enables the USB host support.
     111             :  *
     112             :  * @param[in] uhs_ctx Pointer to USB host support context
     113             :  *
     114             :  * @return 0 on success, other values on fail.
     115             :  */
     116           1 : int usbh_enable(struct usbh_contex *uhs_ctx);
     117             : 
     118             : /**
     119             :  * @brief Disable the USB host support
     120             :  *
     121             :  * This function disables the USB host support.
     122             :  *
     123             :  * @param[in] uhs_ctx Pointer to USB host support context
     124             :  *
     125             :  * @return 0 on success, other values on fail.
     126             :  */
     127           1 : int usbh_disable(struct usbh_contex *uhs_ctx);
     128             : 
     129             : /**
     130             :  * @brief Shutdown the USB host support
     131             :  *
     132             :  * This function completely disables the USB host support.
     133             :  *
     134             :  * @param[in] uhs_ctx Pointer to USB host support context
     135             :  *
     136             :  * @return 0 on success, other values on fail.
     137             :  */
     138           1 : int usbh_shutdown(struct usbh_contex *const uhs_ctx);
     139             : 
     140             : /**
     141             :  * @}
     142             :  */
     143             : 
     144             : #ifdef __cplusplus
     145             : }
     146             : #endif
     147             : 
     148             : #endif /* ZEPHYR_INCLUDE_USBH_H_ */