Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Core / AVR8 / Host_AVR8.h @ 978b99e5

History | View | Annotate | Download (14 KB)

1
/*
2
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
*/
8

    
9
/*
10
  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
11

12
  Permission to use, copy, modify, distribute, and sell this
13
  software and its documentation for any purpose is hereby granted
14
  without fee, provided that the above copyright notice appear in
15
  all copies and that both that the copyright notice and this
16
  permission notice and warranty disclaimer appear in supporting
17
  documentation, and that the name of the author not be used in
18
  advertising or publicity pertaining to distribution of the
19
  software without specific, written prior permission.
20

21
  The author disclaim all warranties with regard to this
22
  software, including all implied warranties of merchantability
23
  and fitness.  In no event shall the author be liable for any
24
  special, indirect or consequential damages or any damages
25
  whatsoever resulting from loss of use, data or profits, whether
26
  in an action of contract, negligence or other tortious action,
27
  arising out of or in connection with the use or performance of
28
  this software.
29
*/
30

    
31
/** \file
32
 *  \brief USB Host definitions for the AVR8 microcontrollers.
33
 *  \copydetails Group_Host_AVR8
34
 *
35
 *  \note This file should not be included directly. It is automatically included as needed by the USB driver
36
 *        dispatch header located in LUFA/Drivers/USB/USB.h.
37
 */
38

    
39
/** \ingroup Group_Host
40
 *  \defgroup Group_Host_AVR8 Host Management (AVR8)
41
 *  \brief USB Host definitions for the AVR8 microcontrollers.
42
 *
43
 *  Architecture specific USB Host definitions for the Atmel 8-bit AVR microcontrollers.
44
 *
45
 *  @{
46
 */
47

    
48
#ifndef __USBHOST_AVR8_H__
49
#define __USBHOST_AVR8_H__
50

    
51
        /* Includes: */
52
                #include "../../../../Common/Common.h"
53
                #include "../StdDescriptors.h"
54
                #include "../Pipe.h"
55
                #include "../USBInterrupt.h"
56

    
57
        /* Enable C linkage for C++ Compilers: */
58
                #if defined(__cplusplus)
59
                        extern "C" {
60
                #endif
61

    
62
        /* Preprocessor Checks: */
63
                #if !defined(__INCLUDE_FROM_USB_DRIVER)
64
                        #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
65
                #endif
66

    
67
        /* Public Interface - May be used in end-application: */
68
                /* Macros: */
69
                        /** Indicates the fixed USB device address which any attached device is enumerated to when in
70
                         *  host mode. As only one USB device may be attached to the AVR in host mode at any one time
71
                         *  and that the address used is not important (other than the fact that it is non-zero), a
72
                         *  fixed value is specified by the library.
73
                         */
74
                        #define USB_HOST_DEVICEADDRESS                 1
75

    
76
                        #if !defined(HOST_DEVICE_SETTLE_DELAY_MS) || defined(__DOXYGEN__)
77
                                /** Constant for the delay in milliseconds after a device is connected before the library
78
                                 *  will start the enumeration process. Some devices require a delay of up to 5 seconds
79
                                 *  after connection before the enumeration process can start or incorrect operation will
80
                                 *  occur.
81
                                 *
82
                                 *  The default delay value may be overridden in the user project makefile by defining the
83
                                 *  \c HOST_DEVICE_SETTLE_DELAY_MS token to the required delay in milliseconds, and passed to the
84
                                 *  compiler using the -D switch.
85
                                 */
86
                                #define HOST_DEVICE_SETTLE_DELAY_MS        1000
87
                        #endif
88

    
89
                        /** Enum for the error codes for the \ref EVENT_USB_Host_HostError() event.
90
                         *
91
                         *  \see \ref Group_Events for more information on this event.
92
                         */
93
                        enum USB_Host_ErrorCodes_t
94
                        {
95
                                HOST_ERROR_VBusVoltageDip       = 0, /**< VBUS voltage dipped to an unacceptable level. This
96
                                                                      *   error may be the result of an attached device drawing
97
                                                                      *   too much current from the VBUS line, or due to the
98
                                                                      *   AVR's power source being unable to supply sufficient
99
                                                                      *   current.
100
                                                                      */
101
                        };
102

    
103
                        /** Enum for the error codes for the \ref EVENT_USB_Host_DeviceEnumerationFailed() event.
104
                         *
105
                         *  \see \ref Group_Events for more information on this event.
106
                         */
107
                        enum USB_Host_EnumerationErrorCodes_t
108
                        {
109
                                HOST_ENUMERROR_NoError          = 0, /**< No error occurred. Used internally, this is not a valid
110
                                                                      *   ErrorCode parameter value for the \ref EVENT_USB_Host_DeviceEnumerationFailed()
111
                                                                      *   event.
112
                                                                      */
113
                                HOST_ENUMERROR_WaitStage        = 1, /**< One of the delays between enumeration steps failed
114
                                                                      *   to complete successfully, due to a timeout or other
115
                                                                      *   error.
116
                                                                      */
117
                                HOST_ENUMERROR_NoDeviceDetected = 2, /**< No device was detected, despite the USB data lines
118
                                                                      *   indicating the attachment of a device.
119
                                                                      */
120
                                HOST_ENUMERROR_ControlError     = 3, /**< One of the enumeration control requests failed to
121
                                                                      *   complete successfully.
122
                                                                      */
123
                                HOST_ENUMERROR_PipeConfigError  = 4, /**< The default control pipe (address 0) failed to
124
                                                                      *   configure correctly.
125
                                                                      */
126
                        };
127

    
128
                /* Inline Functions: */
129
                        /** Returns the current USB frame number, when in host mode. Every millisecond the USB bus is active (i.e. not suspended)
130
                         *  the frame number is incremented by one.
131
                         *
132
                         *  \return Current USB frame number from the USB controller.
133
                         */
134
                        static inline uint16_t USB_Host_GetFrameNumber(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
135
                        static inline uint16_t USB_Host_GetFrameNumber(void)
136
                        {
137
                                return UHFNUM;
138
                        }
139

    
140
                        #if !defined(NO_SOF_EVENTS)
141
                                /** Enables the host mode Start Of Frame events. When enabled, this causes the
142
                                 *  \ref EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
143
                                 *  at the start of each USB frame when a device is enumerated while in host mode.
144
                                 *
145
                                 *  \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
146
                                 */
147
                                static inline void USB_Host_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
148
                                static inline void USB_Host_EnableSOFEvents(void)
149
                                {
150
                                        USB_INT_Enable(USB_INT_HSOFI);
151
                                }
152

    
153
                                /** Disables the host mode Start Of Frame events. When disabled, this stops the firing of the
154
                                 *  \ref EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.
155
                                 *
156
                                 *  \note Not available when the NO_SOF_EVENTS compile time token is defined.
157
                                 */
158
                                static inline void USB_Host_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
159
                                static inline void USB_Host_DisableSOFEvents(void)
160
                                {
161
                                        USB_INT_Disable(USB_INT_HSOFI);
162
                                }
163
                        #endif
164

    
165
                        /** Resets the USB bus, including the endpoints in any attached device and pipes on the AVR host.
166
                         *  USB bus resets leave the default control pipe configured (if already configured).
167
                         *
168
                         *  If the USB bus has been suspended prior to issuing a bus reset, the attached device will be
169
                         *  woken up automatically and the bus resumed after the reset has been correctly issued.
170
                         */
171
                        static inline void USB_Host_ResetBus(void) ATTR_ALWAYS_INLINE;
172
                        static inline void USB_Host_ResetBus(void)
173
                        {
174
                                UHCON |=  (1 << RESET);
175
                        }
176

    
177
                        /** Determines if a previously issued bus reset (via the \ref USB_Host_ResetBus() macro) has
178
                         *  completed.
179
                         *
180
                         *  \return Boolean \c true if no bus reset is currently being sent, \c false otherwise.
181
                         */
182
                        static inline bool USB_Host_IsBusResetComplete(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
183
                        static inline bool USB_Host_IsBusResetComplete(void)
184
                        {
185
                                return ((UHCON & (1 << RESET)) ? false : true);
186
                        }
187

    
188
                        /** Resumes USB communications with an attached and enumerated device, by resuming the transmission
189
                         *  of the 1MS Start Of Frame messages to the device. When resumed, USB communications between the
190
                         *  host and attached device may occur.
191
                         */
192
                        static inline void USB_Host_ResumeBus(void) ATTR_ALWAYS_INLINE;
193
                        static inline void USB_Host_ResumeBus(void)
194
                        {
195
                                UHCON |=  (1 << SOFEN);
196
                        }
197

    
198
                        /** Suspends the USB bus, preventing any communications from occurring between the host and attached
199
                         *  device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame
200
                         *  messages to the device.
201
                         *
202
                         *  \note While the USB bus is suspended, all USB interrupt sources are also disabled; this means that
203
                         *        some events (such as device disconnections) will not fire until the bus is resumed.
204
                         */
205
                        static inline void USB_Host_SuspendBus(void) ATTR_ALWAYS_INLINE;
206
                        static inline void USB_Host_SuspendBus(void)
207
                        {
208
                                UHCON &= ~(1 << SOFEN);
209
                        }
210

    
211
                        /** Determines if the USB bus has been suspended via the use of the \ref USB_Host_SuspendBus() macro,
212
                         *  false otherwise. While suspended, no USB communications can occur until the bus is resumed,
213
                         *  except for the Remote Wakeup event from the device if supported.
214
                         *
215
                         *  \return Boolean \c true if the bus is currently suspended, \c false otherwise.
216
                         */
217
                        static inline bool USB_Host_IsBusSuspended(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
218
                        static inline bool USB_Host_IsBusSuspended(void)
219
                        {
220
                                return ((UHCON & (1 << SOFEN)) ? false : true);
221
                        }
222

    
223
                        /** Determines if the attached device is currently enumerated in Full Speed mode (12Mb/s), or
224
                         *  false if the attached device is enumerated in Low Speed mode (1.5Mb/s).
225
                         *
226
                         *  \return Boolean \c true if the attached device is enumerated in Full Speed mode, \c false otherwise.
227
                         */
228
                        static inline bool USB_Host_IsDeviceFullSpeed(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
229
                        static inline bool USB_Host_IsDeviceFullSpeed(void)
230
                        {
231
                                return ((USBSTA & (1 << SPEED)) ? true : false);
232
                        }
233

    
234
                        /** Determines if the attached device is currently issuing a Remote Wakeup request, requesting
235
                         *  that the host resume the USB bus and wake up the device, false otherwise.
236
                         *
237
                         *  \return Boolean \c true if the attached device has sent a Remote Wakeup request, \c false otherwise.
238
                         */
239
                        static inline bool USB_Host_IsRemoteWakeupSent(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
240
                        static inline bool USB_Host_IsRemoteWakeupSent(void)
241
                        {
242
                                return ((UHINT & (1 << RXRSMI)) ? true : false);
243
                        }
244

    
245
                        /** Clears the flag indicating that a Remote Wakeup request has been issued by an attached device. */
246
                        static inline void USB_Host_ClearRemoteWakeupSent(void) ATTR_ALWAYS_INLINE;
247
                        static inline void USB_Host_ClearRemoteWakeupSent(void)
248
                        {
249
                                UHINT &= ~(1 << RXRSMI);
250
                        }
251

    
252
                        /** Accepts a Remote Wakeup request from an attached device. This must be issued in response to
253
                         *  a device's Remote Wakeup request within 2ms for the request to be accepted and the bus to
254
                         *  be resumed.
255
                         */
256
                        static inline void USB_Host_ResumeFromWakeupRequest(void) ATTR_ALWAYS_INLINE;
257
                        static inline void USB_Host_ResumeFromWakeupRequest(void)
258
                        {
259
                                UHCON |=  (1 << RESUME);
260
                        }
261

    
262
                        /** Determines if a resume from Remote Wakeup request is currently being sent to an attached
263
                         *  device.
264
                         *
265
                         *  \return Boolean \c true if no resume request is currently being sent, \c false otherwise.
266
                         */
267
                        static inline bool USB_Host_IsResumeFromWakeupRequestSent(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
268
                        static inline bool USB_Host_IsResumeFromWakeupRequestSent(void)
269
                        {
270
                                return ((UHCON & (1 << RESUME)) ? false : true);
271
                        }
272

    
273
        /* Private Interface - For use in library only: */
274
        #if !defined(__DOXYGEN__)
275
                /* Macros: */
276
                        static inline void USB_Host_HostMode_On(void) ATTR_ALWAYS_INLINE;
277
                        static inline void USB_Host_HostMode_On(void)
278
                        {
279
                                USBCON |=  (1 << HOST);
280
                        }
281

    
282
                        static inline void USB_Host_HostMode_Off(void) ATTR_ALWAYS_INLINE;
283
                        static inline void USB_Host_HostMode_Off(void)
284
                        {
285
                                USBCON &= ~(1 << HOST);
286
                        }
287

    
288
                        static inline void USB_Host_VBUS_Auto_Enable(void) ATTR_ALWAYS_INLINE;
289
                        static inline void USB_Host_VBUS_Auto_Enable(void)
290
                        {
291
                                OTGCON &= ~(1 << VBUSHWC);
292
                                UHWCON |=  (1 << UVCONE);
293
                        }
294

    
295
                        static inline void USB_Host_VBUS_Manual_Enable(void) ATTR_ALWAYS_INLINE;
296
                        static inline void USB_Host_VBUS_Manual_Enable(void)
297
                        {
298
                                OTGCON |=  (1 << VBUSHWC);
299
                                UHWCON &= ~(1 << UVCONE);
300

    
301
                                DDRE   |=  (1 << 7);
302
                        }
303

    
304
                        static inline void USB_Host_VBUS_Auto_On(void) ATTR_ALWAYS_INLINE;
305
                        static inline void USB_Host_VBUS_Auto_On(void)
306
                        {
307
                                OTGCON |=  (1 << VBUSREQ);
308
                        }
309

    
310
                        static inline void USB_Host_VBUS_Manual_On(void) ATTR_ALWAYS_INLINE;
311
                        static inline void USB_Host_VBUS_Manual_On(void)
312
                        {
313
                                PORTE  |=  (1 << 7);
314
                        }
315

    
316
                        static inline void USB_Host_VBUS_Auto_Off(void) ATTR_ALWAYS_INLINE;
317
                        static inline void USB_Host_VBUS_Auto_Off(void)
318
                        {
319
                                OTGCON |=  (1 << VBUSRQC);
320
                        }
321

    
322
                        static inline void USB_Host_VBUS_Manual_Off(void) ATTR_ALWAYS_INLINE;
323
                        static inline void USB_Host_VBUS_Manual_Off(void)
324
                        {
325
                                PORTE  &= ~(1 << 7);
326
                        }
327

    
328
                        static inline void USB_Host_SetDeviceAddress(const uint8_t Address) ATTR_ALWAYS_INLINE;
329
                        static inline void USB_Host_SetDeviceAddress(const uint8_t Address)
330
                        {
331
                                UHADDR  =  (Address & 0x7F);
332
                        }
333

    
334
                /* Enums: */
335
                        enum USB_Host_WaitMSErrorCodes_t
336
                        {
337
                                HOST_WAITERROR_Successful       = 0,
338
                                HOST_WAITERROR_DeviceDisconnect = 1,
339
                                HOST_WAITERROR_PipeError        = 2,
340
                                HOST_WAITERROR_SetupStalled     = 3,
341
                        };
342

    
343
                /* Function Prototypes: */
344
                        void    USB_Host_ProcessNextHostState(void);
345
                        uint8_t USB_Host_WaitMS(uint8_t MS);
346

    
347
                        #if defined(__INCLUDE_FROM_HOST_C)
348
                                static void USB_Host_ResetDevice(void);
349
                        #endif
350
        #endif
351

    
352
        /* Disable C linkage for C++ Compilers: */
353
                #if defined(__cplusplus)
354
                        }
355
                #endif
356

    
357
#endif
358

    
359
/** @} */
360