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_ */ 280
