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