Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Core / USBTask.h @ 978b99e5

History | View | Annotate | Download (8.87 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 Main USB service task management.
33
 *
34
 *  This file contains the function definitions required for the main USB service task, which must be called
35
 *  from the user application to ensure that the USB connection to or from a connected USB device is maintained.
36
 *
37
 *  \note This file should not be included directly. It is automatically included as needed by the USB driver
38
 *        dispatch header located in LUFA/Drivers/USB/USB.h.
39
 */
40

    
41
#ifndef __USBTASK_H__
42
#define __USBTASK_H__
43

    
44
        /* Includes: */
45
                #include "../../../Common/Common.h"
46
                #include "USBMode.h"                
47
                #include "USBController.h"
48
                #include "Events.h"
49
                #include "StdRequestType.h"
50
                #include "StdDescriptors.h"
51

    
52
                #if defined(USB_CAN_BE_DEVICE)
53
                        #include "DeviceStandardReq.h"
54
                #endif
55

    
56
                #if defined(USB_CAN_BE_HOST)
57
                        #include "HostStandardReq.h"
58
                #endif
59

    
60
        /* Enable C linkage for C++ Compilers: */
61
                #if defined(__cplusplus)
62
                        extern "C" {
63
                #endif
64

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

    
70
        /* Public Interface - May be used in end-application: */
71
                /* Global Variables: */
72
                        /** Indicates if the USB interface is currently initialized but not necessarily connected to a host
73
                         *  or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals related
74
                         *  to the USB driver are invalid.
75
                         *
76
                         *  \note This variable should be treated as read-only in the user application, and never manually
77
                         *        changed in value.
78
                         *
79
                         *  \ingroup Group_USBManagement
80
                         */
81
                        extern volatile bool USB_IsInitialized;
82

    
83
                        /** Structure containing the last received Control request when in Device mode (for use in user-applications
84
                         *  inside of the \ref EVENT_USB_Device_ControlRequest() event, or for filling up with a control request to 
85
                         *  issue when in Host mode before calling \ref USB_Host_SendControlRequest().
86
                         *
87
                         *  \note The contents of this structure is automatically endian-corrected for the current CPU architecture.
88
                         *
89
                         *  \ingroup Group_USBManagement
90
                         */
91
                         extern USB_Request_Header_t USB_ControlRequest;
92

    
93
                        #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)
94
                                #if !defined(HOST_STATE_AS_GPIOR) || defined(__DOXYGEN__)
95
                                        /** Indicates the current host state machine state. When in host mode, this indicates the state
96
                                         *  via one of the values of the \ref USB_Host_States_t enum values.
97
                                         *
98
                                         *  This value should not be altered by the user application as it is handled automatically by the
99
                                         *  library.
100
                                         *
101
                                         *  To reduce program size and speed up checks of this global on the AVR8 architecture, it can be
102
                                         *  placed into one of the AVR's \c GPIOR hardware registers instead of RAM by defining the
103
                                         *  \c HOST_STATE_AS_GPIOR token to a value between 0 and 2 in the project makefile and passing it to
104
                                         *  the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used
105
                                         *  in the user application except implicitly via the library APIs.
106
                                         *
107
                                         *  \note This global is only present if the user application can be a USB host.
108
                                         *
109
                                         *  \see \ref USB_Host_States_t for a list of possible device states.
110
                                         *
111
                                         *  \ingroup Group_Host
112
                                         */
113
                                        extern volatile uint8_t USB_HostState;
114
                                #else
115
                                        #define _GET_HOST_GPIOR_NAME2(y) GPIOR ## y
116
                                        #define _GET_HOST_GPIOR_NAME(x)  _GET_HOST_GPIOR_NAME2(x)
117
                                        #define USB_HostState            _GET_HOST_GPIOR_NAME(HOST_STATE_AS_GPIOR)
118
                                #endif
119
                        #endif
120

    
121
                        #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)
122
                                #if !defined(DEVICE_STATE_AS_GPIOR) || defined(__DOXYGEN__)
123
                                        /** Indicates the current device state machine state. When in device mode, this indicates the state
124
                                         *  via one of the values of the \ref USB_Device_States_t enum values.
125
                                         *
126
                                         *  This value should not be altered by the user application as it is handled automatically by the
127
                                         *  library. The only exception to this rule is if the NO_LIMITED_CONTROLLER_CONNECT token is used
128
                                         *  (see \ref EVENT_USB_Device_Connect() and \ref EVENT_USB_Device_Disconnect() events).
129
                                         *
130
                                         *  To reduce program size and speed up checks of this global on the AVR8 architecture, it can be
131
                                         *  placed into one of the AVR's \c GPIOR hardware registers instead of RAM by defining the
132
                                         *  \c DEVICE_STATE_AS_GPIOR token to a value between 0 and 2 in the project makefile and passing it to
133
                                         *  the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used
134
                                         *  in the user application except implicitly via the library APIs.
135
                                         *
136
                                         *  \note This global is only present if the user application can be a USB device.
137
                                         *        \n\n
138
                                         *
139
                                         *  \note This variable should be treated as read-only in the user application, and never manually
140
                                         *        changed in value except in the circumstances outlined above.
141
                                         *
142
                                         *  \see \ref USB_Device_States_t for a list of possible device states.
143
                                         *
144
                                         *  \ingroup Group_Device
145
                                         */
146
                                        extern volatile uint8_t USB_DeviceState;
147
                                #else
148
                                        #define _GET_DEVICE_GPIOR_NAME2(y) GPIOR ## y
149
                                        #define _GET_DEVICE_GPIOR_NAME(x)  _GET_DEVICE_GPIOR_NAME2(x)
150
                                        #define USB_DeviceState            _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR)
151
                                #endif
152
                        #endif
153

    
154
                /* Function Prototypes: */
155
                        /** This is the main USB management task. The USB driver requires this task to be executed
156
                         *  continuously when the USB system is active (device attached in host mode, or attached to a host
157
                         *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,
158
                         *  fast timer ISR or the main user application loop.
159
                         *
160
                         *  The USB task must be serviced within 30ms while in device mode, or within 1ms while in host mode.
161
                         *  The task may be serviced at all times, or (for minimum CPU consumption):
162
                         *
163
                         *    - In device mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Device_Connect()
164
                         *      event and disabled again on the firing of the \ref EVENT_USB_Device_Disconnect() event.
165
                         *
166
                         *    - In host mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Host_DeviceAttached()
167
                         *      event and disabled again on the firing of the \ref EVENT_USB_Host_DeviceEnumerationComplete() or
168
                         *      \ref EVENT_USB_Host_DeviceEnumerationFailed() events.
169
                         *
170
                         *  If in device mode (only), the control endpoint can instead be managed via interrupts entirely by the library
171
                         *  by defining the INTERRUPT_CONTROL_ENDPOINT token and passing it to the compiler via the -D switch.
172
                         *
173
                         *  \see \ref Group_Events for more information on the USB events.
174
                         *
175
                         *  \ingroup Group_USBManagement
176
                         */
177
                        void USB_USBTask(void);
178

    
179
        /* Private Interface - For use in library only: */
180
        #if !defined(__DOXYGEN__)
181
                /* Function Prototypes: */
182
                        #if defined(__INCLUDE_FROM_USBTASK_C)
183
                                #if defined(USB_CAN_BE_HOST)
184
                                        static void USB_HostTask(void);
185
                                #endif
186

    
187
                                #if defined(USB_CAN_BE_DEVICE)
188
                                        static void USB_DeviceTask(void);
189
                                #endif
190
                        #endif
191

    
192
                /* Macros: */
193
                        #define HOST_TASK_NONBLOCK_WAIT(Duration, NextState) MACROS{ USB_HostState   = HOST_STATE_WaitForDevice; \
194
                                                                                     WaitMSRemaining = (Duration);               \
195
                                                                                     PostWaitState   = (NextState);              }MACROE
196
        #endif
197

    
198
        /* Disable C linkage for C++ Compilers: */
199
                #if defined(__cplusplus)
200
                        }
201
                #endif
202

    
203
#endif
204