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:        24. January 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 /**
  60 \brief USB Device State
  61 */
  62 typedef struct _ARM_USBD_STATE {
  63   uint32_t vbus     : 1;                ///< USB Device VBUS flag
  64   uint32_t speed    : 2;                ///< USB Device speed setting (ARM_USB_SPEED_xxx)
  65   uint32_t active   : 1;                ///< USB Device active flag
  66   uint32_t reserved : 28;
  67 } ARM_USBD_STATE;
  68
  69
  70 /****** USB Device Event *****/
  71 #define ARM_USBD_EVENT_VBUS_ON          (1UL << 0)      ///< USB Device VBUS On
  72 #define ARM_USBD_EVENT_VBUS_OFF         (1UL << 1)      ///< USB Device VBUS Off
  73 #define ARM_USBD_EVENT_RESET            (1UL << 2)      ///< USB Reset occurred
  74 #define ARM_USBD_EVENT_HIGH_SPEED       (1UL << 3)      ///< USB switch to High Speed occurred
  75 #define ARM_USBD_EVENT_SUSPEND          (1UL << 4)      ///< USB Suspend occurred
  76 #define ARM_USBD_EVENT_RESUME           (1UL << 5)      ///< USB Resume occurred
  77
  78 /****** USB Endpoint Event *****/
  79 #define ARM_USBD_EVENT_SETUP            (1UL << 0)      ///< SETUP Packet
  80 #define ARM_USBD_EVENT_OUT              (1UL << 1)      ///< OUT Packet(s)
  81 #define ARM_USBD_EVENT_IN               (1UL << 2)      ///< IN Packet(s)
  82
  83
  84 #ifndef __DOXYGEN_MW__                  // exclude from middleware documentation
  85
  86 // Function documentation
  87 /**
  88   \fn          ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
  89   \brief       Get driver version.
  90   \return      \ref ARM_DRIVER_VERSION
  91 */
  92 /**
  93   \fn          ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
  94   \brief       Get driver capabilities.
  95   \return      \ref ARM_USBD_CAPABILITIES
  96 */
  97 /**
  98   \fn          int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t   cb_device_event,
  99                                             ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 100   \brief       Initialize USB Device Interface.
 101   \param[in]   cb_device_event    Pointer to \ref ARM_USBD_SignalDeviceEvent
 102   \param[in]   cb_endpoint_event  Pointer to \ref ARM_USBD_SignalEndpointEvent
 103   \return      \ref execution_status
 104 */
 105 /**
 106   \fn          int32_t ARM_USBD_Uninitialize (void)
 107   \brief       De-initialize USB Device Interface.
 108   \return      \ref execution_status
 109 */
 110 /**
 111   \fn          int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
 112   \brief       Control USB Device Interface Power.
 113   \param[in]   state  Power state
 114   \return      \ref execution_status
 115 */
 116 /**
 117   \fn          int32_t ARM_USBD_DeviceConnect (void)
 118   \brief       Connect USB Device.
 119   \return      \ref execution_status
 120 */
 121 /**
 122   \fn          int32_t ARM_USBD_DeviceDisconnect (void)
 123   \brief       Disconnect USB Device.
 124   \return      \ref execution_status
 125 */
 126 /**
 127   \fn          ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
 128   \brief       Get current USB Device State.
 129   \return      Device State \ref ARM_USBD_STATE
 130 */
 131 /**
 132   \fn          int32_t ARM_USBD_DeviceRemoteWakeup (void)
 133   \brief       Trigger USB Remote Wakeup.
 134   \return      \ref execution_status
 135 */
 136 /**
 137   \fn          int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
 138   \brief       Set USB Device Address.
 139   \detail      This function is called after status stage of Set Address request
 140                (after IN packet in status stage was sent with old address).
 141   \param[in]   dev_addr  Device Address
 142   \return      \ref execution_status
 143 */
 144 /**
 145   \fn          int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 146   \brief       Read setup packet received over Control Endpoint.
 147   \param[out]  setup  Pointer to buffer for setup packet
 148   \return      \ref execution_status
 149 */
 150 /**
 151   \fn          int32_t ARM_USBD_EndpointConfigure (uint8_t  ep_addr,
 152                                                    uint8_t  ep_type,
 153                                                    uint16_t ep_max_packet_size)
 154   \brief       Configure USB Endpoint.
 155   \param[in]   ep_addr  Endpoint Address
 156                 - ep_addr.0..3: Address
 157                 - ep_addr.7:    Direction
 158   \param[in]   ep_type  Endpoint Type (ARM_USB_ENDPOINT_xxx)
 159   \param[in]   ep_max_packet_size Endpoint Maximum Packet Size
 160   \return      \ref execution_status
 161 */
 162 /**
 163   \fn          int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 164   \brief       Unconfigure USB Endpoint.
 165   \param[in]   ep_addr  Endpoint Address
 166                 - ep_addr.0..3: Address
 167                 - ep_addr.7:    Direction
 168   \return      \ref execution_status
 169 */
 170 /**
 171   \fn          int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 172   \brief       Set/Clear Stall for USB Endpoint.
 173   \param[in]   ep_addr  Endpoint Address
 174                 - ep_addr.0..3: Address
 175                 - ep_addr.7:    Direction
 176   \param[in]   stall  Operation
 177                 - \b false Clear
 178                 - \b true Set
 179   \return      \ref execution_status
 180 */
 181 /**
 182   \fn          int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 183   \brief       Read data from or Write data to USB Endpoint.
 184   \param[in]   ep_addr  Endpoint Address
 185                 - ep_addr.0..3: Address
 186                 - ep_addr.7:    Direction
 187   \param[out]  data Pointer to buffer for data to read or with data to write
 188   \param[in]   num  Number of data bytes to transfer
 189   \return      \ref execution_status
 190 */
 191 /**
 192   \fn          uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 193   \brief       Get result of USB Endpoint transfer.
 194   \param[in]   ep_addr  Endpoint Address
 195                 - ep_addr.0..3: Address
 196                 - ep_addr.7:    Direction
 197   \return      number of successfully transferred data bytes
 198 */
 199 /**
 200   \fn          int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 201   \brief       Abort current USB Endpoint transfer.
 202   \param[in]   ep_addr  Endpoint Address
 203                 - ep_addr.0..3: Address
 204                 - ep_addr.7:    Direction
 205   \return      \ref execution_status
 206 */
 207 /**
 208   \fn          uint16_t ARM_USBD_GetFrameNumber (void)
 209   \brief       Get current USB Frame Number.
 210   \return      Frame Number
 211 */
 212
 213 /**
 214   \fn          void ARM_USBD_SignalDeviceEvent (uint32_t event)
 215   \brief       Signal USB Device Event.
 216   \param[in]   event \ref USBD_dev_events
 217   \return      none
 218 */
 219 /**
 220   \fn          void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event)
 221   \brief       Signal USB Endpoint Event.
 222   \param[in]   ep_addr  Endpoint Address
 223                 - ep_addr.0..3: Address
 224                 - ep_addr.7:    Direction
 225   \param[in]   event \ref USBD_ep_events
 226   \return      none
 227 */
 228
 229 typedef void (*ARM_USBD_SignalDeviceEvent_t)   (uint32_t event);                    ///< Pointer to \ref ARM_USBD_SignalDeviceEvent : Signal USB Device Event.
 230 typedef void (*ARM_USBD_SignalEndpointEvent_t) (uint8_t ep_addr, uint32_t event);   ///< Pointer to \ref ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event.
 231
 232
 233 /**
 234 \brief USB Device Driver Capabilities.
 235 */
 236 typedef struct _ARM_USBD_CAPABILITIES {
 237   uint32_t vbus_detection  : 1;         ///< VBUS detection
 238   uint32_t event_vbus_on   : 1;         ///< Signal VBUS On event
 239   uint32_t event_vbus_off  : 1;         ///< Signal VBUS Off event
 240   uint32_t reserved        : 29;        ///< Reserved (must be zero)
 241 } ARM_USBD_CAPABILITIES;
 242
 243
 244 /**
 245 \brief Access structure of the USB Device Driver.
 246 */
 247 typedef struct _ARM_DRIVER_USBD {
 248   ARM_DRIVER_VERSION    (*GetVersion)                (void);                                              ///< Pointer to \ref ARM_USBD_GetVersion : Get driver version.
 249   ARM_USBD_CAPABILITIES (*GetCapabilities)           (void);                                              ///< Pointer to \ref ARM_USBD_GetCapabilities : Get driver capabilities.
 250   int32_t               (*Initialize)                (ARM_USBD_SignalDeviceEvent_t   cb_device_event,
 251                                                       ARM_USBD_SignalEndpointEvent_t cb_endpoint_event);  ///< Pointer to \ref ARM_USBD_Initialize : Initialize USB Device Interface.
 252   int32_t               (*Uninitialize)              (void);                                              ///< Pointer to \ref ARM_USBD_Uninitialize : De-initialize USB Device Interface.
 253   int32_t               (*PowerControl)              (ARM_POWER_STATE state);                             ///< Pointer to \ref ARM_USBD_PowerControl : Control USB Device Interface Power.
 254   int32_t               (*DeviceConnect)             (void);                                              ///< Pointer to \ref ARM_USBD_DeviceConnect : Connect USB Device.
 255   int32_t               (*DeviceDisconnect)          (void);                                              ///< Pointer to \ref ARM_USBD_DeviceDisconnect : Disconnect USB Device.
 256   ARM_USBD_STATE        (*DeviceGetState)            (void);                                              ///< Pointer to \ref ARM_USBD_DeviceGetState : Get current USB Device State.
 257   int32_t               (*DeviceRemoteWakeup)        (void);                                              ///< Pointer to \ref ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup.
 258   int32_t               (*DeviceSetAddress)          (uint8_t dev_addr);                                  ///< Pointer to \ref ARM_USBD_DeviceSetAddress : Set USB Device Address.
 259   int32_t               (*ReadSetupPacket)           (uint8_t *setup);                                    ///< Pointer to \ref ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint.
 260   int32_t               (*EndpointConfigure)         (uint8_t ep_addr,
 261                                                       uint8_t ep_type,
 262                                                       uint16_t ep_max_packet_size);                       ///< Pointer to \ref ARM_USBD_EndpointConfigure : Configure USB Endpoint.
 263   int32_t               (*EndpointUnconfigure)       (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint.
 264   int32_t               (*EndpointStall)             (uint8_t ep_addr, bool stall);                       ///< Pointer to \ref ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint.
 265   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.
 266   uint32_t              (*EndpointTransferGetResult) (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer.
 267   int32_t               (*EndpointTransferAbort)     (uint8_t ep_addr);                                   ///< Pointer to \ref ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer.
 268   uint16_t              (*GetFrameNumber)            (void);                                              ///< Pointer to \ref ARM_USBD_GetFrameNumber : Get current USB Frame Number.
 269 } const ARM_DRIVER_USBD;
 270
 271 #endif /* __DOXYGEN_MW__ */
 272
 273 #ifdef  __cplusplus
 274 }
 275 #endif
 276
 277 #endif /* DRIVER_USBD_H_ */