X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/8f6b4ddf764c3a54e42d00a7502c82c5c3e71b1c..03ee87b35abdb8b92e8b55ec040fa943f9a6786c:/LUFA/Drivers/USB/HighLevel/USBTask.h?ds=sidebyside diff --git a/LUFA/Drivers/USB/HighLevel/USBTask.h b/LUFA/Drivers/USB/HighLevel/USBTask.h index bcf117ddb..68d04af66 100644 --- a/LUFA/Drivers/USB/HighLevel/USBTask.h +++ b/LUFA/Drivers/USB/HighLevel/USBTask.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) - - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -27,12 +27,6 @@ arising out of or in connection with the use or performance of this software. */ - -/** \file - * - * Main library USB management task for both Host and Device mode operations. This contains the master - * USB_USBTask task which should be periodically run to service both host and device USB projects. - */ #ifndef __USBTASK_H__ #define __USBTASK_H__ @@ -40,46 +34,31 @@ /* Includes: */ #include #include - #include #include - #include - #include "../../../Scheduler/Scheduler.h" #include "../LowLevel/LowLevel.h" - #include "USBMode.h" #include "Events.h" + #include "StdRequestType.h" #include "StdDescriptors.h" + #include "USBMode.h" + + #if defined(USB_CAN_BE_DEVICE) + #include "../LowLevel/DevChapter9.h" + #endif #if defined(USB_CAN_BE_HOST) #include "../LowLevel/HostChapter9.h" - #endif + #endif /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif - + /* Public Interface - May be used in end-application: */ /* Global Variables: */ - /** Indicates if the USB interface is currently connected to a host if in device mode, or to a - * device while running in host mode. - * - * \note This variable should be treated as read-only in the user application, and never manually - * changed in value. - * - * \note For the smaller USB AVRs (AT90USBXX2) with limited USB controllers, VBUS is not available to the USB controller. - * this means that the current connection state is derived from the bus suspension and wake up events by default, - * which is not always accurate (host may suspend the bus while still connected). If the actual connection state - * needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by - * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. - * - * \ingroup Group_USBManagement - */ - extern volatile bool USB_IsConnected; - /** Indicates if the USB interface is currently initialized but not necessarily connected to a host - * or device (i.e. if USB_Init() has been run). If this is false, all other library globals are invalid. + * or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals are invalid. * * \note This variable should be treated as read-only in the user application, and never manually * changed in value. @@ -88,103 +67,99 @@ */ extern volatile bool USB_IsInitialized; - #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) - /** Indicates if the USB interface is currently suspended by the host when in device mode. When suspended, - * the device should consume minimal power, and cannot communicate to the host. If Remote Wakeup is - * supported by the device and USB_RemoteWakeupEnabled is true, suspension can be terminated by the device - * by issuing a Remote Wakup request. - * - * \note This global is only present if the user application can be a USB device. + /** Structure containing the last received Control request when in Device mode (for use in user-applications + * inside of the \ref EVENT_USB_Device_UnhandledControlRequest() event, or for filling up with a control request to issue when + * in Host mode before calling \ref USB_Host_SendControlRequest(). * - * \note This variable should be treated as read-only in the user application, and never manually - * changed in value. - * - * \ingroup Group_Device + * \ingroup Group_USBManagement */ - extern volatile bool USB_IsSuspended; - #endif - + extern USB_Request_Header_t USB_ControlRequest; + #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) - /** Indicates the current host state machine state. When in host mode, this indicates the state - * via one of the values of the USB_Host_States_t enum values in Host.h. - * - * This value may be altered by the user application to implement the HOST_STATE_Addressed, - * HOST_STATE_Configured, HOST_STATE_Ready and HOST_STATE_Suspended states which are not implemented - * by the library. - * - * \note This global is only present if the user application can be a USB host. - * - * \ingroup Group_Host - */ - extern volatile uint8_t USB_HostState; + #if !defined(HOST_STATE_AS_GPIOR) || defined(__DOXYGEN__) + /** Indicates the current host state machine state. When in host mode, this indicates the state + * via one of the values of the \ref USB_Host_States_t enum values. + * + * This value may be altered by the user application to implement the \ref HOST_STATE_Addressed, + * \ref HOST_STATE_Configured and \ref HOST_STATE_Suspended states which are not implemented by + * the library. + * + * To reduce program size and speed up checks of this global, it can be placed into one of the AVR's + * GPIOR hardware registers instead of RAM by defining the HOST_STATE_AS_GPIOR token to a value + * between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When + * defined, the corresponding GPIOR register should not be used in the user application except + * implicitly via the library APIs. + * + * \note This global is only present if the user application can be a USB host. + * + * \see \ref USB_Host_States_t for a list of possible device states + * + * \ingroup Group_Host + */ + extern volatile uint8_t USB_HostState; + #else + #define _GET_HOST_GPIOR_NAME2(y) GPIOR ## y + #define _GET_HOST_GPIOR_NAME(x) _GET_HOST_GPIOR_NAME2(x) + #define USB_HostState _GET_HOST_GPIOR_NAME(HOST_STATE_AS_GPIOR) + #endif #endif - /* Throwable Events: */ - #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) - /** This module raises the USB Connect event when a USB device has been connected whilst in host - * mode, but not yet enumerated. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_Connect); - - /** This module raises the USB Device Attached event when in host mode, and a device is attached - * to the AVR's USB interface. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_DeviceAttached); - - /** This module raises the USB Device Unattached event when in host mode, and a device is removed - * from the AVR's USB interface. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_DeviceUnattached); - - /** This module raises the USB Device Enumeration Failed event when in host mode, and an - * attached USB device has failed to successfully enumerated. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_DeviceEnumerationFailed); - - /** This module raises the USB Device Enumeration Complete event when in host mode, and an - * attached USB device has been successfully enumerated and ready to be used by the user - * application. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_DeviceEnumerationComplete); - - /** This module raises the USB Disconnect event when an attached USB device is removed from the USB - * bus. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_Disconnect); + #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) + #if !defined(DEVICE_STATE_AS_GPIOR) || defined(__DOXYGEN__) + /** Indicates the current device state machine state. When in device mode, this indicates the state + * via one of the values of the \ref USB_Device_States_t enum values. + * + * This value should not be altered by the user application as it is handled automatically by the + * library. The only exception to this rule is if the NO_LIMITED_CONTROLLER_CONNECT token is used + * (see \ref EVENT_USB_Device_Connect() and \ref EVENT_USB_Device_Disconnect() events). + * + * To reduce program size and speed up checks of this global, it can be placed into one of the AVR's + * GPIOR hardware registers instead of RAM by defining the DEVICE_STATE_AS_GPIOR token to a value + * between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When + * defined, the corresponding GPIOR register should not be used in the user application except + * implicitly via the library APIs. + * + * \note This global is only present if the user application can be a USB device. + * + * \note This variable should be treated as read-only in the user application, and never manually + * changed in value except in the circumstances outlined above. + * + * \see \ref USB_Device_States_t for a list of possible device states + * + * \ingroup Group_Device + */ + extern volatile uint8_t USB_DeviceState; + #else + #define _GET_DEVICE_GPIOR_NAME2(y) GPIOR ## y + #define _GET_DEVICE_GPIOR_NAME(x) _GET_DEVICE_GPIOR_NAME2(x) + #define USB_DeviceState _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR) + #endif #endif - /* Tasks: */ + /* Function Prototypes: */ /** This is the main USB management task. The USB driver requires that this task be executed * continuously when the USB system is active (device attached in host mode, or attached to a host * in device mode) in order to manage USB communications. This task may be executed inside an RTOS, - * scheduler (e.g. the simple LUFA Scheduler), fast timer ISR or the main user application loop. + * fast timer ISR or the main user application loop. + * + * The USB task must be serviced within 30ms while in device mode, or within 1ms while in host mode. + * The task may be serviced at all times, or (for minimum CPU consumption): * - * The USB task must be serviced within 50mS in all modes, when needed. The task may be serviced - * at all times, or (for minimum CPU consumption): + * - In device mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Device_Connect() + * event and disabled again on the firing of the \ref EVENT_USB_Device_Disconnect() event. * - * - In device mode, it may be disabled at start-up, enabled on the firing of the USB_Connect event - * and disabled again on the firing of the USB_Disconnect event. + * - In host mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Host_DeviceAttached() + * event and disabled again on the firing of the \ref EVENT_USB_Host_DeviceEnumerationComplete() or + * \ref EVENT_USB_Host_DeviceEnumerationFailed() events. * - * - In host mode, it may be disabled at start-up, enabled on the firing of the USB_DeviceAttached - * event and disabled again on the firing of the USB_DeviceUnattached event. + * If in device mode (only), the control endpoint can instead be managed via interrupts entirely by the library + * by defining the INTERRUPT_CONTROL_ENDPOINT token and passing it to the compiler via the -D switch. * - * \see Events.h for more information on the USB events. + * \see \ref Group_Events for more information on the USB events. * * \ingroup Group_USBManagement */ - TASK(USB_USBTask); + void USB_USBTask(void); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -200,7 +175,9 @@ #endif /* Macros: */ - #define HOST_TASK_NONBLOCK_WAIT(duration, nextstate) {USB_HostState = HOST_STATE_WaitForDevice; WaitMSRemaining = duration; PostWaitState = nextstate; } + #define HOST_TASK_NONBLOCK_WAIT(duration, nextstate) MACROS{ USB_HostState = HOST_STATE_WaitForDevice; \ + WaitMSRemaining = (duration); \ + PostWaitState = (nextstate); }MACROE #endif /* Disable C linkage for C++ Compilers: */