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 Host Driver definitions 22 */ 23 24 /* History: 25 * Version 2.3 26 * Removed volatile from ARM_USBH_PORT_STATE 27 * Version 2.2 28 * ARM_USBH_PORT_STATE made volatile 29 * Version 2.1 30 * Renamed structure ARM_USBH_EP_HANDLE to ARM_USBH_PIPE_HANDLE 31 * Renamed functions ARM_USBH_Endpoint... to ARM_USBH_Pipe... 32 * Renamed function ARM_USBH_SignalEndpointEvent to ARM_USBH_SignalPipeEvent 33 * Version 2.0 34 * Replaced function ARM_USBH_PortPowerOnOff with ARM_USBH_PortVbusOnOff 35 * Changed function ARM_USBH_EndpointCreate parameters 36 * Replaced function ARM_USBH_EndpointConfigure with ARM_USBH_EndpointModify 37 * Replaced function ARM_USBH_EndpointClearHalt with ARM_USBH_EndpointReset 38 * Replaced function ARM_USBH_URB_Submit with ARM_USBH_EndpointTransfer 39 * Replaced function ARM_USBH_URB_Abort with ARM_USBH_EndpointTransferAbort 40 * Added function ARM_USBH_EndpointTransferGetResult 41 * Added function ARM_USBH_GetFrameNumber 42 * Changed prefix ARM_DRV -> ARM_DRIVER 43 * Version 1.20 44 * Added API for OHCI/EHCI Host Controller Interface (HCI) 45 * Version 1.10 46 * Namespace prefix ARM_ added 47 * Version 1.00 48 * Initial release 49 */ 50 51 #ifndef DRIVER_USBH_H_ 52 #define DRIVER_USBH_H_ 53 54 #ifdef __cplusplus 55 extern "C" 56 { 57 #endif 58 59 #include "Driver_USB.h" 60 61 #define ARM_USBH_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,3) /* API version */ 62 63 64 #define _ARM_Driver_USBH_(n) Driver_USBH##n 65 #define ARM_Driver_USBH_(n) _ARM_Driver_USBH_(n) 66 67 68 /** 69 \brief USB Host Port State 70 */ 71 typedef struct _ARM_USBH_PORT_STATE { 72 uint32_t connected : 1; ///< USB Host Port connected flag 73 uint32_t overcurrent : 1; ///< USB Host Port overcurrent flag 74 uint32_t speed : 2; ///< USB Host Port speed setting (ARM_USB_SPEED_xxx) 75 uint32_t reserved : 28; 76 } ARM_USBH_PORT_STATE; 77 78 /** 79 \brief USB Host Pipe Handle 80 */ 81 typedef uint32_t ARM_USBH_PIPE_HANDLE; 82 #define ARM_USBH_EP_HANDLE ARM_USBH_PIPE_HANDLE /* Legacy name */ 83 84 85 /****** USB Host Packet Information *****/ 86 #define ARM_USBH_PACKET_TOKEN_Pos 0 87 #define ARM_USBH_PACKET_TOKEN_Msk (0x0FUL << ARM_USBH_PACKET_TOKEN_Pos) 88 #define ARM_USBH_PACKET_SETUP (0x01UL << ARM_USBH_PACKET_TOKEN_Pos) ///< SETUP Packet 89 #define ARM_USBH_PACKET_OUT (0x02UL << ARM_USBH_PACKET_TOKEN_Pos) ///< OUT Packet 90 #define ARM_USBH_PACKET_IN (0x03UL << ARM_USBH_PACKET_TOKEN_Pos) ///< IN Packet 91 #define ARM_USBH_PACKET_PING (0x04UL << ARM_USBH_PACKET_TOKEN_Pos) ///< PING Packet 92 93 #define ARM_USBH_PACKET_DATA_Pos 4 94 #define ARM_USBH_PACKET_DATA_Msk (0x0FUL << ARM_USBH_PACKET_DATA_Pos) 95 #define ARM_USBH_PACKET_DATA0 (0x01UL << ARM_USBH_PACKET_DATA_Pos) ///< DATA0 PID 96 #define ARM_USBH_PACKET_DATA1 (0x02UL << ARM_USBH_PACKET_DATA_Pos) ///< DATA1 PID 97 98 #define ARM_USBH_PACKET_SPLIT_Pos 8 99 #define ARM_USBH_PACKET_SPLIT_Msk (0x0FUL << ARM_USBH_PACKET_SPLIT_Pos) 100 #define ARM_USBH_PACKET_SSPLIT (0x08UL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet 101 #define ARM_USBH_PACKET_SSPLIT_S (0x09UL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data Start 102 #define ARM_USBH_PACKET_SSPLIT_E (0x0AUL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data End 103 #define ARM_USBH_PACKET_SSPLIT_S_E (0x0BUL << ARM_USBH_PACKET_SPLIT_Pos) ///< SSPLIT Packet: Data All 104 #define ARM_USBH_PACKET_CSPLIT (0x0CUL << ARM_USBH_PACKET_SPLIT_Pos) ///< CSPLIT Packet 105 106 #define ARM_USBH_PACKET_PRE (1UL << 12) ///< PRE Token 107 108 109 /****** USB Host Port Event *****/ 110 #define ARM_USBH_EVENT_CONNECT (1UL << 0) ///< USB Device Connected to Port 111 #define ARM_USBH_EVENT_DISCONNECT (1UL << 1) ///< USB Device Disconnected from Port 112 #define ARM_USBH_EVENT_OVERCURRENT (1UL << 2) ///< USB Device caused Overcurrent 113 #define ARM_USBH_EVENT_RESET (1UL << 3) ///< USB Reset completed 114 #define ARM_USBH_EVENT_SUSPEND (1UL << 4) ///< USB Suspend occurred 115 #define ARM_USBH_EVENT_RESUME (1UL << 5) ///< USB Resume occurred 116 #define ARM_USBH_EVENT_REMOTE_WAKEUP (1UL << 6) ///< USB Device activated Remote Wakeup 117 118 /****** USB Host Pipe Event *****/ 119 #define ARM_USBH_EVENT_TRANSFER_COMPLETE (1UL << 0) ///< Transfer completed 120 #define ARM_USBH_EVENT_HANDSHAKE_NAK (1UL << 1) ///< NAK Handshake received 121 #define ARM_USBH_EVENT_HANDSHAKE_NYET (1UL << 2) ///< NYET Handshake received 122 #define ARM_USBH_EVENT_HANDSHAKE_MDATA (1UL << 3) ///< MDATA Handshake received 123 #define ARM_USBH_EVENT_HANDSHAKE_STALL (1UL << 4) ///< STALL Handshake received 124 #define ARM_USBH_EVENT_HANDSHAKE_ERR (1UL << 5) ///< ERR Handshake received 125 #define ARM_USBH_EVENT_BUS_ERROR (1UL << 6) ///< Bus Error detected 126 127 128 #ifndef __DOXYGEN_MW__ // exclude from middleware documentation 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 \return none 279 */ 280 /** 281 \fn void ARM_USBH_SignalPipeEvent (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event) 282 \brief Signal Pipe Event. 283 \param[in] pipe_hndl Pipe Handle 284 \param[in] event \ref USBH_pipe_events 285 \return none 286 */ 287 288 typedef void (*ARM_USBH_SignalPortEvent_t) (uint8_t port, uint32_t event); ///< Pointer to \ref ARM_USBH_SignalPortEvent : Signal Root HUB Port Event. 289 typedef void (*ARM_USBH_SignalPipeEvent_t) (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event); ///< Pointer to \ref ARM_USBH_SignalPipeEvent : Signal Pipe Event. 290 #define ARM_USBH_SignalEndpointEvent_t ARM_USBH_SignalPipeEvent_t /* Legacy name */ 291 292 293 /** 294 \brief USB Host Driver Capabilities. 295 */ 296 typedef struct _ARM_USBH_CAPABILITIES { 297 uint32_t port_mask : 15; ///< Root HUB available Ports Mask 298 uint32_t auto_split : 1; ///< Automatic SPLIT packet handling 299 uint32_t event_connect : 1; ///< Signal Connect event 300 uint32_t event_disconnect : 1; ///< Signal Disconnect event 301 uint32_t event_overcurrent : 1; ///< Signal Overcurrent event 302 uint32_t reserved : 13; ///< Reserved (must be zero) 303 } ARM_USBH_CAPABILITIES; 304 305 306 /** 307 \brief Access structure of USB Host Driver. 308 */ 309 typedef struct _ARM_DRIVER_USBH { 310 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBH_GetVersion : Get driver version. 311 ARM_USBH_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USBH_GetCapabilities : Get driver capabilities. 312 int32_t (*Initialize) (ARM_USBH_SignalPortEvent_t cb_port_event, 313 ARM_USBH_SignalPipeEvent_t cb_pipe_event); ///< Pointer to \ref ARM_USBH_Initialize : Initialize USB Host Interface. 314 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USBH_Uninitialize : De-initialize USB Host Interface. 315 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USBH_PowerControl : Control USB Host Interface Power. 316 int32_t (*PortVbusOnOff) (uint8_t port, bool vbus); ///< Pointer to \ref ARM_USBH_PortVbusOnOff : Root HUB Port VBUS on/off. 317 int32_t (*PortReset) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortReset : Do Root HUB Port Reset. 318 int32_t (*PortSuspend) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs). 319 int32_t (*PortResume) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs). 320 ARM_USBH_PORT_STATE (*PortGetState) (uint8_t port); ///< Pointer to \ref ARM_USBH_PortGetState : Get current Root HUB Port State. 321 ARM_USBH_PIPE_HANDLE (*PipeCreate) (uint8_t dev_addr, 322 uint8_t dev_speed, 323 uint8_t hub_addr, 324 uint8_t hub_port, 325 uint8_t ep_addr, 326 uint8_t ep_type, 327 uint16_t ep_max_packet_size, 328 uint8_t ep_interval); ///< Pointer to \ref ARM_USBH_PipeCreate : Create Pipe in System. 329 int32_t (*PipeModify) (ARM_USBH_PIPE_HANDLE pipe_hndl, 330 uint8_t dev_addr, 331 uint8_t dev_speed, 332 uint8_t hub_addr, 333 uint8_t hub_port, 334 uint16_t ep_max_packet_size); ///< Pointer to \ref ARM_USBH_PipeModify : Modify Pipe in System. 335 int32_t (*PipeDelete) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeDelete : Delete Pipe from System. 336 int32_t (*PipeReset) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeReset : Reset Pipe. 337 int32_t (*PipeTransfer) (ARM_USBH_PIPE_HANDLE pipe_hndl, 338 uint32_t packet, 339 uint8_t *data, 340 uint32_t num); ///< Pointer to \ref ARM_USBH_PipeTransfer : Transfer packets through USB Pipe. 341 uint32_t (*PipeTransferGetResult) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeTransferGetResult : Get result of USB Pipe transfer. 342 int32_t (*PipeTransferAbort) (ARM_USBH_PIPE_HANDLE pipe_hndl); ///< Pointer to \ref ARM_USBH_PipeTransferAbort : Abort current USB Pipe transfer. 343 uint16_t (*GetFrameNumber) (void); ///< Pointer to \ref ARM_USBH_GetFrameNumber : Get current USB Frame Number. 344 } const ARM_DRIVER_USBH; 345 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 \return none 391 */ 392 393 typedef void (*ARM_USBH_HCI_Interrupt_t) (void); ///< Pointer to Interrupt Handler Routine. 394 395 396 /** 397 \brief USB Host HCI (OHCI/EHCI) Driver Capabilities. 398 */ 399 typedef struct _ARM_USBH_HCI_CAPABILITIES { 400 uint32_t port_mask : 15; ///< Root HUB available Ports Mask 401 uint32_t reserved : 17; ///< Reserved (must be zero) 402 } ARM_USBH_HCI_CAPABILITIES; 403 404 405 /** 406 \brief Access structure of USB Host HCI (OHCI/EHCI) Driver. 407 */ 408 typedef struct _ARM_DRIVER_USBH_HCI { 409 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBH_HCI_GetVersion : Get USB Host HCI (OHCI/EHCI) driver version. 410 ARM_USBH_HCI_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USBH_HCI_GetCapabilities : Get driver capabilities. 411 int32_t (*Initialize) (ARM_USBH_HCI_Interrupt_t cb_interrupt); ///< Pointer to \ref ARM_USBH_HCI_Initialize : Initialize USB Host HCI (OHCI/EHCI) Interface. 412 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USBH_HCI_Uninitialize : De-initialize USB Host HCI (OHCI/EHCI) Interface. 413 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USBH_HCI_PowerControl : Control USB Host HCI (OHCI/EHCI) Interface Power. 414 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. 415 } const ARM_DRIVER_USBH_HCI; 416 417 #endif /* __DOXYGEN_MW__ */ 418 419 #ifdef __cplusplus 420 } 421 #endif 422 423 #endif /* DRIVER_USBH_H_ */ 424
