Added standard stream example to the ClassDriver CDC device demo.

[pub/USBasp.git] / LUFA / Drivers / USB / HighLevel / USBTask.h

diff --git a/LUFA/Drivers/USB/HighLevel/USBTask.h b/LUFA/Drivers/USB/HighLevel/USBTask.h
index 1fcc2bb..9601315 100644 (file)
--- a/LUFA/Drivers/USB/HighLevel/USBTask.h
+++ b/LUFA/Drivers/USB/HighLevel/USBTask.h
@@ -27,12 +27,6 @@
   arising out of or in connection with the use or performance of\r
   this software.\r
 */\r
   arising out of or in connection with the use or performance of\r
   this software.\r
 */\r

-\r
-/** \file\r
- *\r
- *  Main library USB management task for both Host and Device mode operations. This contains the master\r
- *  USB_USBTask task which should be periodically run to service both host and device USB projects.\r
- */\r

  \r
 #ifndef __USBTASK_H__\r
 #define __USBTASK_H__\r
  \r
 #ifndef __USBTASK_H__\r
 #define __USBTASK_H__\r


@@ -44,134 +38,126 @@
                #include <stdbool.h>\r
                #include <stddef.h>\r
                \r
                #include <stdbool.h>\r
                #include <stddef.h>\r
                \r

-               #include "../../../Scheduler/Scheduler.h"\r

                #include "../LowLevel/LowLevel.h"\r
                #include "../LowLevel/LowLevel.h"\r

-               #include "../LowLevel/HostChapter9.h"\r
-               #include "../LowLevel/USBMode.h"\r
+               #include "StdRequestType.h"\r
+               #include "USBMode.h"\r

                #include "Events.h"\r
                #include "StdDescriptors.h"\r
                #include "Events.h"\r
                #include "StdDescriptors.h"\r

+\r
+               #if defined(USB_CAN_BE_HOST)\r
+                       #include "../LowLevel/HostChapter9.h"\r
+               #endif          \r

                \r
        /* Enable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r
                        extern "C" {\r
                #endif\r
                \r
        /* Enable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r
                        extern "C" {\r
                #endif\r

-\r
+               \r

        /* Public Interface - May be used in end-application: */\r
                /* Global Variables: */\r
        /* Public Interface - May be used in end-application: */\r
                /* Global Variables: */\r

-                       /** Indicates if the USB interface is currently connected to a host if in device mode, or to a\r
-                        *  device while running in host mode.\r
+                       /** Indicates if the USB interface is currently initialized but not necessarily connected to a host\r
+                        *  or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals are invalid.\r

                         *\r
                         *  \note This variable should be treated as read-only in the user application, and never manually\r
                         *        changed in value.\r
                         *\r
                         *\r
                         *  \note This variable should be treated as read-only in the user application, and never manually\r
                         *        changed in value.\r
                         *\r

-                        *  \note For the smaller USB AVRs (AT90USBXX2) with limited USB controllers, VBUS is not available to the USB controller.\r
-                        *        this means that the current connection state is derived from the bus suspension and wake up events by default,\r
-                        *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state\r
-                        *        needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by\r
-                        *        passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection\r
-                        *        and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually.\r
-                        */\r
-                       extern volatile bool USB_IsConnected;\r
-\r
-                       /** Indicates if the USB interface is currently initialized but not neccesarily connected to a host\r
-                        *  or device (i.e. if USB_Init() has been run). If this is false, all other library globals are invalid.\r
-                        *\r
-                        *  \note This variable should be treated as read-only in the user application, and never manually\r
-                        *        changed in value.\r
+                        *  \ingroup Group_USBManagement\r

                         */\r
                        extern volatile bool USB_IsInitialized;\r
 \r
                         */\r
                        extern volatile bool USB_IsInitialized;\r
 \r

-                       #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)\r
-                       /** Indicates if the USB interface is currently suspended by the host when in device mode. When suspended,\r
-                        *  the device should consume minimal power, and cannot communicate to the host. If Remote Wakeup is\r
-                        *  supported by the device and USB_RemoteWakeupEnabled is true, suspension can be terminated by the device\r
-                        *  by issuing a Remote Wakup request.\r
+                       /** Structure containing the last received Control request when in Device mode (for use in user-applications\r
+                        *  inside of the \ref EVENT_USB_UnhandledControlPacket() event, or for filling up with a control request to issue when\r
+                        *  in Host mode before calling \ref USB_Host_SendControlRequest().\r

                         *\r
                         *\r

-                        *  \note This global is only present if the user application can be a USB device.\r
-                        *\r
-                        *  \note This variable should be treated as read-only in the user application, and never manually\r
-                        *        changed in value.\r
+                        *  \ingroup Group_USBManagement\r

                         */\r
                         */\r

-                       extern volatile bool USB_IsSuspended;\r
-                       #endif\r
-\r
+                        extern USB_Request_Header_t USB_ControlRequest;\r
+                       \r

                        #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)\r
                        #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)\r

-                       /** Indicates the current host state machine state. When in host mode, this indicates the state\r
-                        *  via one of the values of the USB_Host_States_t enum values in Host.h.\r
-                        *\r
-                        *  This value may be altered by the user application to implement the HOST_STATE_Addressed,\r
-                        *  HOST_STATE_Configured, HOST_STATE_Ready and HOST_STATE_Suspended states which are not implemented\r
-                        *  by the library.\r
-                        *\r
-                        *  \note This global is only present if the user application can be a USB host.\r
-                        */\r
-                       extern volatile uint8_t USB_HostState;\r
+                               #if !defined(HOST_STATE_AS_GPIOR1) || defined(__DOXYGEN__)\r
+                                       /** Indicates the current host state machine state. When in host mode, this indicates the state\r
+                                        *  via one of the values of the \ref USB_Host_States_t enum values.\r
+                                        *\r
+                                        *  This value may be altered by the user application to implement the \ref HOST_STATE_Addressed,\r
+                                        *  \ref HOST_STATE_Configured and \ref HOST_STATE_Suspended states which are not implemented by\r
+                                        *  the library.\r
+                                        *\r
+                                        *  To reduce program size and speed up checks of this global, it can be placed into one of the AVR's\r
+                                        *  GPIOR hardware registers instead of RAM by defining the HOST_STATE_AS_GPIOR token to a value \r
+                                        *  between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When\r
+                                        *  defined, the corresponding GPIOR register should not be used in the user application except\r
+                                        *  implicitly via the library APIs.\r
+                                        *\r
+                                        *  \note This global is only present if the user application can be a USB host.\r
+                                        *\r
+                                        *  \see \ref USB_Host_States_t for a list of possible device states\r
+                                        *\r
+                                        *  \ingroup Group_Host\r
+                                        */\r
+                                       extern volatile uint8_t USB_HostState;\r
+                               #else\r
+                                       #define _GET_HOST_GPIOR_NAME2(y) GPIOR ## y\r
+                                       #define _GET_HOST_GPIOR_NAME(x)  _GET_HOST_GPIOR_NAME2(x)\r
+                                       #define USB_HostState _GET_HOST_GPIOR_NAME(HOST_STATE_AS_GPIOR)\r
+                               #endif\r

                        #endif\r
 \r
                        #endif\r
 \r

-               /* Throwable Events: */\r
-                       #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)\r
-                               /** This module raises the USB Connect event when a USB device has been connected whilst in host\r
-                                *  mode, but not yet enumerated.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_Connect);\r
-\r
-                               /** This module raises the USB Device Attached event when in host mode, and a device is attached\r
-                                *  to the AVR's USB interface.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_DeviceAttached);\r
-\r
-                               /** This module raises the USB Device Unattached event when in host mode, and a device is removed\r
-                                *  from the AVR's USB interface.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_DeviceUnattached);\r
-                               \r
-                               /** This module raises the USB Device Enumeration Failed event when in host mode, and an\r
-                                *  attached USB device has failed to successfully enumerated.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_DeviceEnumerationFailed);\r
-\r
-                               /** This module raises the USB Device Enumeration Complete event when in host mode, and an\r
-                                *  attached USB device has been successfully enumerated and ready to be used by the user\r
-                                *  application.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_DeviceEnumerationComplete);\r
-\r
-                               /** This module raises the USB Disconnect event when an attached USB device is removed from the USB\r
-                                *  bus.\r
-                                *\r
-                                *  \see Events.h for more information on this event.\r
-                                */\r
-                               RAISES_EVENT(USB_Disconnect);\r
+                       #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)\r
+                               #if !defined(DEVICE_STATE_AS_GPIOR) || defined(__DOXYGEN__)\r
+                                       /** Indicates the current device state machine state. When in device mode, this indicates the state\r
+                                        *  via one of the values of the \ref USB_Device_States_t enum values.\r
+                                        *\r
+                                        *  This value should not be altered by the user application as it is handled automatically by the\r
+                                        *  library. The only exception to this rule is if the NO_LIMITED_CONTROLLER_CONNECT token is used\r
+                                        *  (see \ref EVENT_USB_Connect() and \ref EVENT_USB_Disconnect() events).\r
+                                        *\r
+                                        *  To reduce program size and speed up checks of this global, it can be placed into one of the AVR's\r
+                                        *  GPIOR hardware registers instead of RAM by defining the DEVICE_STATE_AS_GPIOR token to a value \r
+                                        *  between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When\r
+                                        *  defined, the corresponding GPIOR register should not be used in the user application except\r
+                                        *  implicitly via the library APIs.\r
+                                        *\r
+                                        *  \note This global is only present if the user application can be a USB device.\r
+                                        *\r
+                                        *  \note This variable should be treated as read-only in the user application, and never manually\r
+                                        *        changed in value except in the circumstances outlined above.\r
+                                        *\r
+                                        *  \see \ref USB_Device_States_t for a list of possible device states\r
+                                        *\r
+                                        *  \ingroup Group_Device\r
+                                        */\r
+                                       extern volatile uint8_t USB_DeviceState;\r
+                               #else\r
+                                       #define _GET_DEVICE_GPIOR_NAME2(y) GPIOR ## y\r
+                                       #define _GET_DEVICE_GPIOR_NAME(x)  _GET_DEVICE_GPIOR_NAME2(x)\r
+                                       #define USB_DeviceState _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR)\r
+                               #endif\r

                        #endif\r
 \r
                        #endif\r
 \r

-               /* Tasks: */\r
+               /* Function Prototypes: */\r

                        /** This is the main USB management task. The USB driver requires that this task be executed\r
                         *  continuously when the USB system is active (device attached in host mode, or attached to a host\r
                         *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,\r
                        /** This is the main USB management task. The USB driver requires that this task be executed\r
                         *  continuously when the USB system is active (device attached in host mode, or attached to a host\r
                         *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,\r

-                        *  scheduler (e.g. the simple LUFA Scheduler), fast timer ISR or the main user application loop.\r
+                        *  fast timer ISR or the main user application loop.\r
+                        *\r
+                        *  The USB task must be serviced within 30ms while in device mode, or within 1ms while in host mode.\r
+                        *  The task may be serviced at all times, or (for minimum CPU consumption):\r
+                        *\r
+                        *    - In device mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Connect() event\r
+                        *    and disabled again on the firing of the \ref EVENT_USB_Disconnect() event.\r

                         *\r
                         *\r

-                        *  The USB task must be serviced within 50mS in all modes, when needed. The task may be serviced \r
-                        *  at all times, or (for minimum CPU consumption):\r
+                        *    - In host mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_DeviceAttached()\r
+                        *    event and disabled again on the firing of the \ref EVENT_USB_DeviceEnumerationComplete() or\r
+                        *    \ref EVENT_USB_DeviceEnumerationFailed() events.\r

                         *\r
                         *\r

-                        *    - In device mode, it may be disabled at startup, enabled on the firing of the USB_Connect event\r
-                        *    and disabled again on the firing of the USB_Disconnect event.\r
+                        *  If in device mode (only), the control endpoint can instead be managed via interrupts entirely by the library\r
+                        *  by defining the INTERRUPT_CONTROL_ENDPOINT token and passing it to the compiler via the -D switch.\r

                         *\r
                         *\r

-                        *    - In host mode, it may be disabled at startup, enabled on the firing of the USB_DeviceAttached\r
-                        *    event and disabled again on the firing of the USB_DeviceUnattached event.\r
+                        *  \see \ref Group_Events for more information on the USB events.\r

                         *\r
                         *\r

-                        *  \see Events.h for more information on the USB events.\r
+                        *  \ingroup Group_USBManagement\r

                         */\r
                         */\r

-                       TASK(USB_USBTask);\r
+                       void USB_USBTask(void);\r

 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r
 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r