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

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