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.4 20 * 21 * Project: USB Host Driver definitions 22 */ 23 24 /* History: 25 * Version 2.4 26 * Deprecated API for OHCI/EHCI Host Controller Interface (HCI) 27 * Version 2.3 28 * Removed volatile from ARM_USBH_PORT_STATE 29 * Version 2.2 30 * ARM_USBH_PORT_STATE made volatile 31 * Version 2.1 32 * Renamed structure ARM_USBH_EP_HANDLE to ARM_USBH_PIPE_HANDLE 33 * Renamed functions ARM_USBH_Endpoint... to ARM_USBH_Pipe... 34 * Renamed function ARM_USBH_SignalEndpointEvent to ARM_USBH_SignalPipeEvent 35 * Version 2.0 36 * Replaced function ARM_USBH_PortPowerOnOff with ARM_USBH_PortVbusOnOff 37 * Changed function ARM_USBH_EndpointCreate parameters 38 * Replaced function ARM_USBH_EndpointConfigure with ARM_USBH_EndpointModify 39 * Replaced function ARM_USBH_EndpointClearHalt with ARM_USBH_EndpointReset 40 * Replaced function ARM_USBH_URB_Submit with ARM_USBH_EndpointTransfer 41 * Replaced function ARM_USBH_URB_Abort with ARM_USBH_EndpointTransferAbort 42 * Added function ARM_USBH_EndpointTransferGetResult 43 * Added function ARM_USBH_GetFrameNumber 44 * Changed prefix ARM_DRV -> ARM_DRIVER 45 * Version 1.20 46 * Added API for OHCI/EHCI Host Controller Interface (HCI) 47 * Version 1.10 48 * Namespace prefix ARM_ added 49 * Version 1.00 50 * Initial release 51 */ 52 53 #ifndef DRIVER_USBH_H_ 54 #define DRIVER_USBH_H_ 55 56 #ifdef __cplusplus 57 extern "C" 58 { 59 #endif 60 61 #include "Driver_USB.h" 62 63 #define ARM_USBH_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,4) /* API version */ 64 65 66 #define _ARM_Driver_USBH_(n) Driver_USBH##n 67 #define ARM_Driver_USBH_(n) _ARM_Driver_USBH_(n) 68 69 70 /** 71 \brief USB Host Port State 72 */ 73 typedef struct _ARM_USBH_PORT_STATE { 74 uint32_t connected : 1; ///< USB Host Port connected flag 75 uint32_t overcurrent : 1; ///< USB Host Port overcurrent flag 76 uint32_t speed : 2; ///< USB Host Port speed setting (ARM_USB_SPEED_xxx) 77 uint32_t reserved : 28; 78 } ARM_USBH_PORT_STATE; 79 80 /** 81 \brief USB Host Pipe Handle 82 */ 83 typedef uint32_t ARM_USBH_PIPE_HANDLE; 84 #define ARM_USBH_EP_HANDLE ARM_USBH_PIPE_HANDLE /* Legacy name */ 85 86 87 /****** USB Host Packet Information *****/ 88 #define ARM_USBH_PACKET_TOKEN_Pos 0 89 #define ARM_USBH_PACKET_TOKEN_Msk (0x0FUL << ARM_USBH_PACKET_TOKEN_Pos) 90 #define ARM_USBH_PACKET_SETUP (0x01UL << ARM_USBH_PACKET_TOKEN_Pos) ///< SETUP Packet 91 #define ARM_USBH_PACKET_OUT (0x02UL << ARM_USBH_PACKET_TOKEN_Pos) ///< OUT Packet 92 #define ARM_USBH_PACKET_IN (0x03UL << ARM_USBH_PACKET_TOKEN_Pos) ///< IN Packet 93 #define ARM_USBH_PACKET_PING (0x04UL << ARM_USBH_PACKET_TOKEN_Pos) ///< PING Packet 94 95 #define ARM_USBH_PACKET_DATA_Pos 4 96 #define ARM_USBH_PACKET_DATA_Msk (0x0FUL << ARM_USBH_PACKET_DATA_Pos) 97 #define ARM_USBH_PACKET_DATA0 (0x01UL << ARM_USBH_PACKET_DATA_Pos) ///< DATA0 PID 98 #define ARM_USBH_PACKET_DATA1 (0x02UL << ARM_USBH_PACKET_DATA_Pos) ///< DATA1 PID 99 100 #define ARM_USBH_PACKET_SPLIT_Pos 8 101 #define ARM_USBH_PACKET_SPLIT_Msk (0x0FUL << ARM_USBH_PACKET_SPLIT_Pos) 102 #define ARM_USBH_PACKET_SSPLIT (0x08UL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet 103 #define ARM_USBH_PACKET_SSPLIT_S (0x09UL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data Start 104 #define ARM_USBH_PACKET_SSPLIT_E (0x0AUL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data End 105 #define ARM_USBH_PACKET_SSPLIT_S_E (0x0BUL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data All 106 #define ARM_USBH_PACKET_CSPLIT (0x0CUL << ARM_USBH_PACKET_SPLIT_Pos) ///< CSPLIT Packet 107 108 #define ARM_USBH_PACKET_PRE (1UL << 12) ///< PRE Token 109 110 111 /****** USB Host Port Event *****/ 112 #define ARM_USBH_EVENT_CONNECT (1UL << 0) ///< USB Device Connected to Port 113 #define ARM_USBH_EVENT_DISCONNECT (1UL << 1) ///< USB Device Disconnected from Port 114 #define ARM_USBH_EVENT_OVERCURRENT (1UL << 2) ///< USB Device caused Overcurrent 115 #define ARM_USBH_EVENT_RESET (1UL << 3) ///< USB Reset completed 116 #define ARM_USBH_EVENT_SUSPEND (1UL << 4) ///< USB Suspend occurred 117 #define ARM_USBH_EVENT_RESUME (1UL << 5) ///< USB Resume occurred 118 #define ARM_USBH_EVENT_REMOTE_WAKEUP (1UL << 6) ///< USB Device activated Remote Wakeup 119 120 /****** USB Host Pipe Event *****/ 121 #define ARM_USBH_EVENT_TRANSFER_COMPLETE (1UL << 0) ///< Transfer completed 122 #define ARM_USBH_EVENT_HANDSHAKE_NAK (1UL << 1) ///< NAK Handshake received 123 #define ARM_USBH_EVENT_HANDSHAKE_NYET (1UL << 2) ///< NYET Handshake received 124 #define ARM_USBH_EVENT_HANDSHAKE_MDATA (1UL << 3) ///< MDATA Handshake received 125 #define ARM_USBH_EVENT_HANDSHAKE_STALL (1UL << 4) ///< STALL Handshake received 126 #define ARM_USBH_EVENT_HANDSHAKE_ERR (1UL << 5) ///< ERR Handshake received 127 #define ARM_USBH_EVENT_BUS_ERROR (1UL << 6) ///< Bus Error detected 128 129 130 // Function documentation 131 /** 132 \fn ARM_DRIVER_VERSION ARM_USBH_GetVersion (void) 133 \brief Get driver version. 134 \return \ref ARM_DRIVER_VERSION 135 */ 136 /** 137 \fn ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities (void) 138 \brief Get driver capabilities. 139 \return \ref ARM_USBH_CAPABILITIES 140 */ 141 /** 142 \fn int32_t ARM_USBH_Initialize (ARM_USBH_SignalPortEvent_t cb_port_event, 143 ARM_USBH_SignalPipeEvent_t cb_pipe_event) 144 \brief Initialize USB Host Interface. 145 \param[in] cb_port_event Pointer to \ref ARM_USBH_SignalPortEvent 146 \param[in] cb_pipe_event Pointer to \ref ARM_USBH_SignalPipeEvent 147 \return \ref execution_status 148 */ 149 /** 150 \fn int32_t ARM_USBH_Uninitialize (void) 151 \brief De-initialize USB Host Interface. 152 \return \ref execution_status 153 */ 154 /** 155 \fn int32_t ARM_USBH_PowerControl (ARM_POWER_STATE state) 156 \brief Control USB Host Interface Power. 157 \param[in] state Power state 158 \return \ref execution_status 159 */ 160 /** 161 \fn int32_t ARM_USBH_PortVbusOnOff (uint8_t port, bool vbus) 162 \brief Root HUB Port VBUS on/off. 163 \param[in] port Root HUB Port Number 164 \param[in] vbus 165 - \b false VBUS off 166 - \b true VBUS on 167 \return \ref execution_status 168 */ 169 /** 170 \fn int32_t ARM_USBH_PortReset (uint8_t port) 171 \brief Do Root HUB Port Reset. 172 \param[in] port Root HUB Port Number 173 \return \ref execution_status 174 */ 175 /** 176 \fn int32_t ARM_USBH_PortSuspend (uint8_t port) 177 \brief Suspend Root HUB Port (stop generating SOFs). 178 \param[in] port Root HUB Port Number 179 \return \ref execution_status 180 */ 181 /** 182 \fn int32_t ARM_USBH_PortResume (uint8_t port) 183 \brief Resume Root HUB Port (start generating SOFs). 184 \param[in] port Root HUB Port Number 185 \return \ref execution_status 186 */ 187 /** 188 \fn ARM_USBH_PORT_STATE ARM_USBH_PortGetState (uint8_t port) 189 \brief Get current Root HUB Port State. 190 \param[in] port Root HUB Port Number 191 \return Port State \ref ARM_USBH_PORT_STATE 192 */ 193 /** 194 \fn ARM_USBH_PIPE_HANDLE ARM_USBH_PipeCreate (uint8_t dev_addr, 195 uint8_t dev_speed, 196 uint8_t hub_addr, 197 uint8_t hub_port, 198 uint8_t ep_addr, 199 uint8_t ep_type, 200 uint16_t ep_max_packet_size, 201 uint8_t ep_interval) 202 \brief Create Pipe in System. 203 \param[in] dev_addr Device Address 204 \param[in] dev_speed Device Speed 205 \param[in] hub_addr Hub Address 206 \param[in] hub_port Hub Port 207 \param[in] ep_addr Endpoint Address 208 - ep_addr.0..3: Address 209 - ep_addr.7: Direction 210 \param[in] ep_type Endpoint Type (ARM_USB_ENDPOINT_xxx) 211 \param[in] ep_max_packet_size Endpoint Maximum Packet Size 212 \param[in] ep_interval Endpoint Polling Interval 213 \return Pipe Handle \ref ARM_USBH_PIPE_HANDLE 214 */ 215 /** 216 \fn int32_t ARM_USBH_PipeModify (ARM_USBH_PIPE_HANDLE pipe_hndl, 217 uint8_t dev_addr, 218 uint8_t dev_speed, 219 uint8_t hub_addr, 220 uint8_t hub_port, 221 uint16_t ep_max_packet_size) 222 \brief Modify Pipe in System. 223 \param[in] pipe_hndl Pipe Handle 224 \param[in] dev_addr Device Address 225 \param[in] dev_speed Device Speed 226 \param[in] hub_addr Hub Address 227 \param[in] hub_port Hub Port 228 \param[in] ep_max_packet_size Endpoint Maximum Packet Size 229 \return \ref execution_status 230 */ 231 /** 232 \fn int32_t ARM_USBH_PipeDelete (ARM_USBH_PIPE_HANDLE pipe_hndl) 233 \brief Delete Pipe from System. 234 \param[in] pipe_hndl Pipe Handle 235 \return \ref execution_status 236 */ 237 /** 238 \fn int32_t ARM_USBH_PipeReset (ARM_USBH_PIPE_HANDLE pipe_hndl) 239 \brief Reset Pipe. 240 \param[in] pipe_hndl Pipe Handle 241 \return \ref execution_status 242 */ 243 /** 244 \fn int32_t ARM_USBH_PipeTransfer (ARM_USBH_PIPE_HANDLE pipe_hndl, 245 uint32_t packet, 246 uint8_t *data, 247 uint32_t num) 248 \brief Transfer packets through USB Pipe. 249 \param[in] pipe_hndl Pipe Handle 250 \param[in] packet Packet information 251 \param[in] data Pointer to buffer with data to send or for data to receive 252 \param[in] num Number of data bytes to transfer 253 \return \ref execution_status 254 */ 255 /** 256 \fn uint32_t ARM_USBH_PipeTransferGetResult (ARM_USBH_PIPE_HANDLE pipe_hndl) 257 \brief Get result of USB Pipe transfer. 258 \param[in] pipe_hndl Pipe Handle 259 \return number of successfully transferred data bytes 260 */ 261 /** 262 \fn int32_t ARM_USBH_PipeTransferAbort (ARM_USBH_PIPE_HANDLE pipe_hndl) 263 \brief Abort current USB Pipe transfer. 264 \param[in] pipe_hndl Pipe Handle 265 \return \ref execution_status 266 */ 267 /** 268 \fn uint16_t ARM_USBH_GetFrameNumber (void) 269 \brief Get current USB Frame Number. 270 \return Frame Number 271 */ 272 273 /** 274 \fn void ARM_USBH_SignalPortEvent (uint8_t port, uint32_t event) 275 \brief Signal Root HUB Port Event. 276 \param[in] port Root HUB Port Number 277 \param[in] event \ref USBH_port_events 278 */ 279 /** 280 \fn void ARM_USBH_SignalPipeEvent (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event) 281 \brief Signal Pipe Event. 282 \param[in] pipe_hndl Pipe Handle 283 \param[in] event \ref USBH_pipe_events 284 */ 285 286 typedef void (*ARM_USBH_SignalPortEvent_t) (uint8_t port, uint32_t event); ///< Pointer to \ref ARM_USBH_SignalPortEvent : Signal Root HUB Port Event. 287 typedef void (*ARM_USBH_SignalPipeEvent_t) (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event); ///< Pointer to \ref ARM_USBH_SignalPipeEvent : Signal Pipe Event. 288 #define ARM_USBH_SignalEndpointEvent_t ARM_USBH_SignalPipeEvent_t /* Legacy name */ 289 290 291 /** 292 \brief USB Host Driver Capabilities. 293 */ 294 typedef struct _ARM_USBH_CAPABILITIES { 295 uint32_t port_mask : 15; ///< Root HUB available Ports Mask 296 uint32_t auto_split : 1; ///< Automatic SPLIT packet handling 297 uint32_t event_connect : 1; ///< Signal Connect event 298 uint32_t event_disconnect : 1; ///< Signal Disconnect event 299 uint32_t event_overcurrent : 1; ///< Signal Overcurrent event 300 uint32_t reserved : 13; ///< Reserved (must be zero) 301 } ARM_USBH_CAPABILITIES; 302 303 304 /** 305 \brief Access structure of USB Host Driver. 306 */ 307 typedef struct _ARM_DRIVER_USBH { 308 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBH_GetVersion : Get driver version. 309 ARM_USBH_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USBH_GetCapabilities : Get driver capabilities. 310 int32_t (*Initialize) (ARM_USBH_SignalPortEvent_t cb_port_event, 311 ARM_USBH_SignalPipeEvent_t cb_pipe_event); ///< Pointer to \ref ARM_USBH_Initialize : Initialize USB Host Interface. 312 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USBH_Uninitialize : De-initialize USB Host Interface. 313 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USBH_PowerControl : Control USB Host Interface Power. 314 int32_t (*PortVbusOnOff) (uint8_t port, bool vbus); ///< Pointer to \ref ARM_USBH_PortVbusOnOff : Root HUB Port VBUS on/off. 315 int32_t (*PortReset) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortReset : Do Root HUB Port Reset. 316 int32_t (*PortSuspend) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs). 317 int32_t (*PortResume) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs). 318 ARM_USBH_PORT_STATE (*PortGetState) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortGetState : Get current Root HUB Port State. 319 ARM_USBH_PIPE_HANDLE (*PipeCreate) (uint8_t dev_addr, 320 uint8_t dev_speed, 321 uint8_t hub_addr, 322 uint8_t hub_port, 323 uint8_t ep_addr, 324 uint8_t ep_type, 325 uint16_t ep_max_packet_size, 326 uint8_t ep_interval); ///< Pointer to \ref ARM_USBH_PipeCreate : Create Pipe in System. 327 int32_t (*PipeModify) (ARM_USBH_PIPE_HANDLE pipe_hndl, 328 uint8_t dev_addr, 329 uint8_t dev_speed, 330 uint8_t hub_addr, 331 uint8_t hub_port, 332 uint16_t ep_max_packet_size); ///< Pointer to \ref ARM_USBH_PipeModify : Modify Pipe in System. 333 int32_t (*PipeDelete) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeDelete : Delete Pipe from System. 334 int32_t (*PipeReset) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeReset : Reset Pipe. 335 int32_t (*PipeTransfer) (ARM_USBH_PIPE_HANDLE pipe_hndl, 336 uint32_t packet, 337 uint8_t *data, 338 uint32_t num); ///< Pointer to \ref ARM_USBH_PipeTransfer : Transfer packets through USB Pipe. 339 uint32_t (*PipeTransferGetResult) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeTransferGetResult : Get result of USB Pipe transfer. 340 int32_t (*PipeTransferAbort) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeTransferAbort : Abort current USB Pipe transfer. 341 uint16_t (*GetFrameNumber) (void); ///< Pointer to \ref ARM_USBH_GetFrameNumber : Get current USB Frame Number. 342 } const ARM_DRIVER_USBH; 343 344 345 #ifndef CMSIS_DISABLE_DEPRECATED 346 347 // HCI (OHCI/EHCI) 348 349 // Function documentation 350 /** 351 \fn ARM_DRIVER_VERSION ARM_USBH_HCI_GetVersion (void) 352 \brief Get USB Host HCI (OHCI/EHCI) driver version. 353 \return \ref ARM_DRIVER_VERSION 354 */ 355 /** 356 \fn ARM_USBH_HCI_CAPABILITIES ARM_USBH_HCI_GetCapabilities (void) 357 \brief Get driver capabilities. 358 \return \ref ARM_USBH_HCI_CAPABILITIES 359 */ 360 /** 361 \fn int32_t ARM_USBH_HCI_Initialize (ARM_USBH_HCI_Interrupt_t *cb_interrupt) 362 \brief Initialize USB Host HCI (OHCI/EHCI) Interface. 363 \param[in] cb_interrupt Pointer to Interrupt Handler Routine 364 \return \ref execution_status 365 */ 366 /** 367 \fn int32_t ARM_USBH_HCI_Uninitialize (void) 368 \brief De-initialize USB Host HCI (OHCI/EHCI) Interface. 369 \return \ref execution_status 370 */ 371 /** 372 \fn int32_t ARM_USBH_HCI_PowerControl (ARM_POWER_STATE state) 373 \brief Control USB Host HCI (OHCI/EHCI) Interface Power. 374 \param[in] state Power state 375 \return \ref execution_status 376 */ 377 /** 378 \fn int32_t ARM_USBH_HCI_PortVbusOnOff (uint8_t port, bool vbus) 379 \brief USB Host HCI (OHCI/EHCI) Root HUB Port VBUS on/off. 380 \param[in] port Root HUB Port Number 381 \param[in] vbus 382 - \b false VBUS off 383 - \b true VBUS on 384 \return \ref execution_status 385 */ 386 387 /** 388 \fn void ARM_USBH_HCI_Interrupt (void) 389 \brief USB Host HCI Interrupt Handler. 390 */ 391 392 typedef void (*ARM_USBH_HCI_Interrupt_t) (void); ///< Pointer to Interrupt Handler Routine. 393 394 395 /** 396 \brief USB Host HCI (OHCI/EHCI) Driver Capabilities. 397 */ 398 typedef struct _ARM_USBH_HCI_CAPABILITIES { 399 uint32_t port_mask : 15; ///< Root HUB available Ports Mask 400 uint32_t reserved : 17; ///< Reserved (must be zero) 401 } ARM_USBH_HCI_CAPABILITIES; 402 403 404 /** 405 \brief Access structure of USB Host HCI (OHCI/EHCI) Driver. @deprecated HCI driver has been deprecated 406 */ 407 typedef struct _ARM_DRIVER_USBH_HCI { 408 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBH_HCI_GetVersion : Get USB Host HCI (OHCI/EHCI) driver version. 409 ARM_USBH_HCI_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USBH_HCI_GetCapabilities : Get driver capabilities. 410 int32_t (*Initialize) (ARM_USBH_HCI_Interrupt_t cb_interrupt); ///< Pointer to \ref ARM_USBH_HCI_Initialize : Initialize USB Host HCI (OHCI/EHCI) Interface. 411 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USBH_HCI_Uninitialize : De-initialize USB Host HCI (OHCI/EHCI) Interface. 412 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USBH_HCI_PowerControl : Control USB Host HCI (OHCI/EHCI) Interface Power. 413 int32_t (*PortVbusOnOff) (uint8_t port, bool vbus); ///< Pointer to \ref ARM_USBH_HCI_PortVbusOnOff : USB Host HCI (OHCI/EHCI) Root HUB Port VBUS on/off. 414 } const ARM_DRIVER_USBH_HCI; 415 416 #endif // CMSIS_DISABLE_DEPRECATED 417 418 #ifdef __cplusplus 419 } 420 #endif 421 422 #endif /* DRIVER_USBH_H_ */ 423
