begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_USBD.h

   1 /*
   2  * Copyright (c) 2013-2020 ARM Limited. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: Apache-2.0
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License); you may
   7  * not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * $Date:        31. March 2020
  19  * $Revision:    V2.3
  20  *
  21  * Project:      USB Device Driver definitions
  22  */
  23
  24 /* History:
  25  *  Version 2.3
  26  *    Removed volatile from ARM_USBD_STATE
  27  *  Version 2.2
  28  *    ARM_USBD_STATE made volatile
  29  *  Version 2.1
  30  *    Added ARM_USBD_ReadSetupPacket function
  31  *  Version 2.0
  32  *    Removed ARM_USBD_DeviceConfigure function
  33  *    Removed ARM_USBD_SET_ADDRESS_STAGE parameter from ARM_USBD_DeviceSetAddress function
  34  *    Removed ARM_USBD_EndpointReadStart function
  35  *    Replaced ARM_USBD_EndpointRead and ARM_USBD_EndpointWrite functions with ARM_USBD_EndpointTransfer
  36  *    Added ARM_USBD_EndpointTransferGetResult function
  37  *    Renamed ARM_USBD_EndpointAbort function to ARM_USBD_EndpointTransferAbort
  38  *    Changed prefix ARM_DRV -> ARM_DRIVER
  39  *    Changed return values of some functions to int32_t
  40  *  Version 1.10
  41  *    Namespace prefix ARM_ added
  42  *  Version 1.00
  43  *    Initial release
  44  */
  45
  46 #ifndef DRIVER_USBD_H_
  47 #define DRIVER_USBD_H_
  48
  49 #ifdef  __cplusplus
  50 extern "C"
  51 {
  52 #endif
  53
  54 #include "Driver_USB.h"
  55
  56 #define ARM_USBD_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,3)  /* API version */
  57
  58
  59 #define _ARM_Driver_USBD_(n)      Driver_USBD##n
  60 #define  ARM_Driver_USBD_(n) _ARM_Driver_USBD_(n)
  61
  62
  63 /**
  64 \brief USB Device State
  65 */
  66 typedef struct _ARM_USBD_STATE {
  67   uint32_t vbus     : 1;                ///< USB Device VBUS flag
  68   uint32_t speed    : 2;                ///< USB Device speed setting (ARM_USB_SPEED_xxx)
  69   uint32_t active   : 1;                ///< USB Device active flag
  70   uint32_t reserved : 28;
  71 } ARM_USBD_STATE;
  72
  73
  74 /****** USB Device Event *****/
  75 #define ARM_USBD_EVENT_VBUS_ON          (1UL << 0)      ///< USB Device VBUS On
  76 #define ARM_USBD_EVENT_VBUS_OFF         (1UL << 1)      ///< USB Device VBUS Off
  77 #define ARM_USBD_EVENT_RESET            (1UL << 2)      ///< USB Reset occurred
  78 #define ARM_USBD_EVENT_HIGH_SPEED       (1UL << 3)      ///< USB switch to High Speed occurred
  79 #define ARM_USBD_EVENT_SUSPEND          (1UL << 4)      ///< USB Suspend occurred
  80 #define ARM_USBD_EVENT_RESUME           (1UL << 5)      ///< USB Resume occurred
  81
  82 /****** USB Endpoint Event *****/
  83 #define ARM_USBD_EVENT_SETUP            (1UL << 0)      ///< SETUP Packet
  84 #define ARM_USBD_EVENT_OUT              (1UL << 1)      ///< OUT Packet(s)
  85 #define ARM_USBD_EVENT_IN               (1UL << 2)      ///< IN Packet(s)
  86
  87
  88 #ifndef __DOXYGEN_MW__                  // exclude from middleware documentation
  89
  90 // Function documentation
  91 /**
  92   \fn          ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
  93   \brief       Get driver version.
  94   \return      \ref ARM_DRIVER_VERSION
  95 */
  96 /**
  97   \fn          ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
  98   \brief       Get driver capabilities.
  99   \return      \ref ARM_USBD_CAPABILITIES
 100 */
 101 /**
 102   \fn          int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t   cb_device_event,
 103                                             ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 104   \brief       Initialize USB Device Interface.
 105   \param[in]   cb_device_event    Pointer to \ref ARM_USBD_SignalDeviceEvent
 106   \param[in]   cb_endpoint_event  Pointer to \ref ARM_USBD_SignalEndpointEvent
 107   \return      \ref execution_status
 108 */
 109 /**
 110   \fn          int32_t ARM_USBD_Uninitialize (void)
 111   \brief       De-initialize USB Device Interface.
 112   \return      \ref execution_status
 113 */
 114 /**
 115   \fn          int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
 116   \brief       Control USB Device Interface Power.
 117   \param[in]   state  Power state
 118   \return      \ref execution_status
 119 */
 120 /**
 121   \fn          int32_t ARM_USBD_DeviceConnect (void)
 122   \brief       Connect USB Device.
 123   \return      \ref execution_status
 124 */
 125 /**
 126   \fn          int32_t ARM_USBD_DeviceDisconnect (void)
 127   \brief       Disconnect USB Device.
 128   \return      \ref execution_status
 129 */
 130 /**
 131   \fn          ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
 132   \brief       Get current USB Device State.
 133   \return      Device State \ref ARM_USBD_STATE
 134 */
 135 /**
 136   \fn          int32_t ARM_USBD_DeviceRemoteWakeup (void)
 137   \brief       Trigger USB Remote Wakeup.
 138   \return      \ref execution_status
 139 */
 140 /**
 141   \fn          int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
 142   \brief       Set USB Device Address.
 143   \param[in]   dev_addr  Device Address
 144   \return      \ref execution_status
 145 */
 146 /**
 147   \fn          int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 148   \brief       Read setup packet received over Control Endpoint.
 149   \param[out]  setup  Pointer to buffer for setup packet
 150   \return      \ref execution_status
 151 */
 152 /**
 153   \fn          int32_t ARM_USBD_EndpointConfigure (uint8_t  ep_addr,
 154                                                    uint8_t  ep_type,
 155                                                    uint16_t ep_max_packet_size)
 156   \brief       Configure USB Endpoint.
 157   \param[in]   ep_addr  Endpoint Address
 158                 - ep_addr.0..3: Address
 159                 - ep_addr.7:    Direction
 160   \param[in]   ep_type  Endpoint Type (ARM_USB_ENDPOINT_xxx)
 161   \param[in]   ep_max_packet_size Endpoint Maximum Packet Size
 162   \return      \ref execution_status
 163 */
 164 /**
 165   \fn          int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 166   \brief       Unconfigure USB Endpoint.
 167   \param[in]   ep_addr  Endpoint Address
 168                 - ep_addr.0..3: Address
 169                 - ep_addr.7:    Direction
 170   \return      \ref execution_status
 171 */
 172 /**
 173   \fn          int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 174   \brief       Set/Clear Stall for USB Endpoint.
 175   \param[in]   ep_addr  Endpoint Address
 176                 - ep_addr.0..3: Address
 177                 - ep_addr.7:    Direction
 178   \param[in]   stall  Operation
 179                 - \b false Clear
 180                 - \b true Set
 181   \return      \ref execution_status
 182 */
 183 /**
 184   \fn          int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 185   \brief       Read data from or Write data to USB Endpoint.
 186   \param[in]   ep_addr  Endpoint Address
 187                 - ep_addr.0..3: Address
 188                 - ep_addr.7:    Direction
 189   \param[out]  data Pointer to buffer for data to read or with data to write
 190   \param[in]   num  Number of data bytes to transfer
 191   \return      \ref execution_status
 192 */
 193 /**
 194   \fn          uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 195   \brief       Get result of USB Endpoint transfer.
 196   \param[in]   ep_addr  Endpoint Address
 197                 - ep_addr.0..3: Address
 198                 - ep_addr.7:    Direction
 199   \return      number of successfully transferred data bytes
 200 */
 201 /**
 202   \fn          int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 203   \brief       Abort current USB Endpoint transfer.
 204   \param[in]   ep_addr  Endpoint Address
 205                 - ep_addr.0..3: Address
 206                 - ep_addr.7:    Direction
 207   \return      \ref execution_status
 208 */
 209 /**
 210   \fn          uint16_t ARM_USBD_GetFrameNumber (void)
 211   \brief       Get current USB Frame Number.
 212   \return      Frame Number
 213 */
 214
 215 /**
 216   \fn          void ARM_USBD_SignalDeviceEvent (uint32_t event)
 217   \brief       Signal USB Device Event.
 218   \param[in]   event \ref USBD_dev_events
 219   \return      none
 220 */
 221 /**
 222   \fn          void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event)
 223   \brief       Signal USB Endpoint Event.
 224   \param[in]   ep_addr  Endpoint Address
 225                 - ep_addr.0..3: Address
 226                 - ep_addr.7:    Direction
 227   \param[in]   event \ref USBD_ep_events
 228   \return      none
 229 */
 230
 231 typedef void (*ARM_USBD_SignalDeviceEvent_t)   (uint32_t event);                    ///< Pointer to \ref ARM_USBD_SignalDeviceEvent : Signal USB Device Event.
 232 typedef void (*ARM_USBD_SignalEndpointEvent_t) (uint8_t ep_addr, uint32_t event);   ///< Pointer to \ref ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event.
 233
 234
 235 /**
 236 \brief USB Device Driver Capabilities.
 237 */
 238 typedef struct _ARM_USBD_CAPABILITIES {
 239   uint32_t vbus_detection  : 1;         ///< VBUS detection
 240   uint32_t event_vbus_on   : 1;         ///< Signal VBUS On event
 241   uint32_t event_vbus_off  : 1;         ///< Signal VBUS Off event
 242   uint32_t reserved        : 29;        ///< Reserved (must be zero)
 243 } ARM_USBD_CAPABILITIES;
 244
 245
 246 /**
 247 \brief Access structure of the USB Device Driver.
 248 */
 249 typedef struct _ARM_DRIVER_USBD {
 250   ARM_DRIVER_VERSION    (*GetVersion)                (void);                                              ///< Pointer to \ref ARM_USBD_GetVersion : Get driver version.
 251   ARM_USBD_CAPABILITIES (*GetCapabilities)           (void);                                              ///< Pointer to \ref ARM_USBD_GetCapabilities : Get driver capabilities.
 252   int32_t               (*Initialize)                (ARM_USBD_SignalDeviceEvent_t   cb_device_event,
 253                                                       ARM_USBD_SignalEndpointEvent_t cb_endpoint_event);  ///< Pointer to \ref ARM_USBD_Initialize : Initialize USB Device Interface.
 254   int32_t               (*Uninitialize)              (void);                                              ///< Pointer to \ref ARM_USBD_Uninitialize : De-initialize USB Device Interface.
 255   int32_t               (*PowerControl)              (ARM_POWER_STATE state);                             ///< Pointer to \ref ARM_USBD_PowerControl : Control USB Device Interface Power.
 256   int32_t               (*DeviceConnect)             (void);                                              ///< Pointer to \ref ARM_USBD_DeviceConnect : Connect USB Device.
 257   int32_t               (*DeviceDisconnect)          (void);                                              ///< Pointer to \ref ARM_USBD_DeviceDisconnect : Disconnect USB Device.
 258   ARM_USBD_STATE        (*DeviceGetState)            (void);                                              ///< Pointer to \ref ARM_USBD_DeviceGetState : Get current USB Device State.
 259   int32_t               (*DeviceRemoteWakeup)        (void);                                              ///< Pointer to \ref ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup.
 260   int32_t               (*DeviceSetAddress)          (uint8_t dev_addr);                                  ///< Pointer to \ref ARM_USBD_DeviceSetAddress : Set USB Device Address.
 261   int32_t               (*ReadSetupPacket)           (uint8_t *setup);                                    ///< Pointer to \ref ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint.
 262   int32_t               (*EndpointConfigure)         (uint8_t ep_addr,
 263                                                       uint8_t ep_type,
 264                                                       uint16_t ep_max_packet_size);                       ///< Pointer to \ref ARM_USBD_EndpointConfigure : Configure USB Endpoint.
 265   int32_t               (*EndpointUnconfigure)       (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint.
 266   int32_t               (*EndpointStall)             (uint8_t ep_addr, bool stall);                       ///< Pointer to \ref ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint.
 267   int32_t               (*EndpointTransfer)          (uint8_t ep_addr, uint8_t *data, uint32_t num);      ///< Pointer to \ref ARM_USBD_EndpointTransfer : Read data from or Write data to USB Endpoint.
 268   uint32_t              (*EndpointTransferGetResult) (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer.
 269   int32_t               (*EndpointTransferAbort)     (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer.
 270   uint16_t              (*GetFrameNumber)            (void);                                              ///< Pointer to \ref ARM_USBD_GetFrameNumber : Get current USB Frame Number.
 271 } const ARM_DRIVER_USBD;
 272
 273 #endif /* __DOXYGEN_MW__ */
 274
 275 #ifdef  __cplusplus
 276 }
 277 #endif
 278
 279 #endif /* DRIVER_USBD_H_ */