1 /* 2 * Copyright (c) 2013-2024 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: 13. May 2024 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 // Function documentation 89 /** 90 \fn ARM_DRIVER_VERSION ARM_USBD_GetVersion (void) 91 \brief Get driver version. 92 \return \ref ARM_DRIVER_VERSION 93 */ 94 /** 95 \fn ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void) 96 \brief Get driver capabilities. 97 \return \ref ARM_USBD_CAPABILITIES 98 */ 99 /** 100 \fn int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, 101 ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) 102 \brief Initialize USB Device Interface. 103 \param[in] cb_device_event Pointer to \ref ARM_USBD_SignalDeviceEvent 104 \param[in] cb_endpoint_event Pointer to \ref ARM_USBD_SignalEndpointEvent 105 \return \ref execution_status 106 */ 107 /** 108 \fn int32_t ARM_USBD_Uninitialize (void) 109 \brief De-initialize USB Device Interface. 110 \return \ref execution_status 111 */ 112 /** 113 \fn int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state) 114 \brief Control USB Device Interface Power. 115 \param[in] state Power state 116 \return \ref execution_status 117 */ 118 /** 119 \fn int32_t ARM_USBD_DeviceConnect (void) 120 \brief Connect USB Device. 121 \return \ref execution_status 122 */ 123 /** 124 \fn int32_t ARM_USBD_DeviceDisconnect (void) 125 \brief Disconnect USB Device. 126 \return \ref execution_status 127 */ 128 /** 129 \fn ARM_USBD_STATE ARM_USBD_DeviceGetState (void) 130 \brief Get current USB Device State. 131 \return Device State \ref ARM_USBD_STATE 132 */ 133 /** 134 \fn int32_t ARM_USBD_DeviceRemoteWakeup (void) 135 \brief Trigger USB Remote Wakeup. 136 \return \ref execution_status 137 */ 138 /** 139 \fn int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr) 140 \brief Set USB Device 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 */ 218 /** 219 \fn void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event) 220 \brief Signal USB Endpoint Event. 221 \param[in] ep_addr Endpoint Address 222 - ep_addr.0..3: Address 223 - ep_addr.7: Direction 224 \param[in] event \ref USBD_ep_events 225 */ 226 227 typedef void (*ARM_USBD_SignalDeviceEvent_t) (uint32_t event); ///< Pointer to \ref ARM_USBD_SignalDeviceEvent : Signal USB Device Event. 228 typedef void (*ARM_USBD_SignalEndpointEvent_t) (uint8_t ep_addr, uint32_t event); ///< Pointer to \ref ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event. 229 230 231 /** 232 \brief USB Device Driver Capabilities. 233 */ 234 typedef struct _ARM_USBD_CAPABILITIES { 235 uint32_t vbus_detection : 1; ///< VBUS detection 236 uint32_t event_vbus_on : 1; ///< Signal VBUS On event 237 uint32_t event_vbus_off : 1; ///< Signal VBUS Off event 238 uint32_t reserved : 29; ///< Reserved (must be zero) 239 } ARM_USBD_CAPABILITIES; 240 241 242 /** 243 \brief Access structure of the USB Device Driver. 244 */ 245 typedef struct _ARM_DRIVER_USBD { 246 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBD_GetVersion : Get driver version. 247 ARM_USBD_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USBD_GetCapabilities : Get driver capabilities. 248 int32_t (*Initialize) (ARM_USBD_SignalDeviceEvent_t cb_device_event, 249 ARM_USBD_SignalEndpointEvent_t cb_endpoint_event); ///< Pointer to \ref ARM_USBD_Initialize : Initialize USB Device Interface. 250 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USBD_Uninitialize : De-initialize USB Device Interface. 251 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USBD_PowerControl : Control USB Device Interface Power. 252 int32_t (*DeviceConnect) (void); ///< Pointer to \ref ARM_USBD_DeviceConnect : Connect USB Device. 253 int32_t (*DeviceDisconnect) (void); ///< Pointer to \ref ARM_USBD_DeviceDisconnect : Disconnect USB Device. 254 ARM_USBD_STATE (*DeviceGetState) (void); ///< Pointer to \ref ARM_USBD_DeviceGetState : Get current USB Device State. 255 int32_t (*DeviceRemoteWakeup) (void); ///< Pointer to \ref ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup. 256 int32_t (*DeviceSetAddress) (uint8_t dev_addr); ///< Pointer to \ref ARM_USBD_DeviceSetAddress : Set USB Device Address. 257 int32_t (*ReadSetupPacket) (uint8_t *setup); ///< Pointer to \ref ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint. 258 int32_t (*EndpointConfigure) (uint8_t ep_addr, 259 uint8_t ep_type, 260 uint16_t ep_max_packet_size); ///< Pointer to \ref ARM_USBD_EndpointConfigure : Configure USB Endpoint. 261 int32_t (*EndpointUnconfigure) (uint8_t ep_addr); ///< Pointer to \ref ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint. 262 int32_t (*EndpointStall) (uint8_t ep_addr, bool stall); ///< Pointer to \ref ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint. 263 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. 264 uint32_t (*EndpointTransferGetResult) (uint8_t ep_addr); ///< Pointer to \ref ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer. 265 int32_t (*EndpointTransferAbort) (uint8_t ep_addr); ///< Pointer to \ref ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer. 266 uint16_t (*GetFrameNumber) (void); ///< Pointer to \ref ARM_USBD_GetFrameNumber : Get current USB Frame Number. 267 } const ARM_DRIVER_USBD; 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif /* DRIVER_USBD_H_ */ 274
