LUFA/Drivers/USB/HighLevel/USBTask.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2009.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, and distribute this software
  13   and its documentation for any purpose and without fee is hereby
  14   granted, provided that the above copyright notice appear in all
  15   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 #ifndef __USBTASK_H__
  32 #define __USBTASK_H__
  33
  34         /* Includes: */
  35                 #include <avr/io.h>
  36                 #include <avr/interrupt.h>
  37                 #include <util/atomic.h>
  38                 #include <stdbool.h>
  39                 #include <stddef.h>
  40
  41                 #include "../../../Scheduler/Scheduler.h"
  42                 #include "../LowLevel/LowLevel.h"
  43                 #include "StdRequestType.h"
  44                 #include "USBMode.h"
  45                 #include "Events.h"
  46                 #include "StdDescriptors.h"
  47
  48                 #if defined(USB_CAN_BE_HOST)
  49                         #include "../LowLevel/HostChapter9.h"
  50                 #endif
  51
  52         /* Enable C linkage for C++ Compilers: */
  53                 #if defined(__cplusplus)
  54                         extern "C" {
  55                 #endif
  56
  57         /* Public Interface - May be used in end-application: */
  58                 /* Global Variables: */
  59                         /** Indicates if the USB interface is currently connected to a host if in device mode, or to a
  60                          *  device while running in host mode.
  61                          *
  62                          *  \note This variable should be treated as read-only in the user application, and never manually
  63                          *        changed in value.
  64                          *
  65                          *  \note For the smaller USB AVRs (AT90USBXX2) with limited USB controllers, VBUS is not available to the USB controller.
  66                          *        this means that the current connection state is derived from the bus suspension and wake up events by default,
  67                          *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state
  68                          *        needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
  69                          *        passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
  70                          *        and disconnection events may be manually fired by \ref RAISE_EVENT(), and the \ref USB_IsConnected global changed manually.
  71                          *
  72                          *  \ingroup Group_USBManagement
  73                          */
  74                         extern volatile bool USB_IsConnected;
  75
  76                         /** Indicates if the USB interface is currently initialized but not necessarily connected to a host
  77                          *  or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals are invalid.
  78                          *
  79                          *  \note This variable should be treated as read-only in the user application, and never manually
  80                          *        changed in value.
  81                          *
  82                          *  \ingroup Group_USBManagement
  83                          */
  84                         extern volatile bool USB_IsInitialized;
  85
  86                         /** Structure containing the last received Control request when in Device mode (for use in user-applications
  87                          *  inside of the \ref USB_UnhandledControlPacket() event, or for filling up with a control request to issue when
  88                          *  in Host mode before calling \ref USB_Host_SendControlRequest().
  89                          *
  90                          *  \ingroup Group_USBManagement
  91                          */
  92                          extern USB_Request_Header_t USB_ControlRequest;
  93
  94                         #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)
  95                         /** Indicates if the USB interface is currently suspended by the host when in device mode. When suspended,
  96                          *  the device should consume minimal power, and cannot communicate to the host. If Remote Wakeup is
  97                          *  supported by the device and \ref USB_RemoteWakeupEnabled is true, suspension can be terminated by the device
  98                          *  by issuing a Remote Wakeup request.
  99                          *
 100                          *  \note This global is only present if the user application can be a USB device.
 101                          *
 102                          *  \note This variable should be treated as read-only in the user application, and never manually
 103                          *        changed in value.
 104                          *
 105                          *  \ingroup Group_Device
 106                          */
 107                         extern volatile bool USB_IsSuspended;
 108                         #endif
 109
 110                         #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)
 111                         /** Indicates the current host state machine state. When in host mode, this indicates the state
 112                          *  via one of the values of the \ref USB_Host_States_t enum values in Host.h.
 113                          *
 114                          *  This value may be altered by the user application to implement the \ref HOST_STATE_Addressed,
 115                          *  \ref HOST_STATE_Configured, \ref HOST_STATE_Ready and \ref HOST_STATE_Suspended states which
 116                          *  are not implemented by the library.
 117                          *
 118                          *  \note This global is only present if the user application can be a USB host.
 119                          *
 120                          *  \ingroup Group_Host
 121                          */
 122                         extern volatile uint8_t USB_HostState;
 123                         #endif
 124
 125                 /* Throwable Events: */
 126                         #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)
 127                                 /** This module raises the \ref USB_Connect event when a USB device has been connected whilst in host
 128                                  *  mode, but not yet enumerated.
 129                                  *
 130                                  *  \see \ref Group_Events for more information on this event.
 131                                  */
 132                                 RAISES_EVENT(USB_Connect);
 133
 134                                 /** This module raises the \ref USB_DeviceAttached event when in host mode, and a device is attached
 135                                  *  to the AVR's USB interface.
 136                                  *
 137                                  *  \see \ref Group_Events for more information on this event.
 138                                  */
 139                                 RAISES_EVENT(USB_DeviceAttached);
 140
 141                                 /** This module raises the \ref USB_DeviceUnattached event when in host mode, and a device is removed
 142                                  *  from the AVR's USB interface.
 143                                  *
 144                                  *  \see \ref Group_Events for more information on this event.
 145                                  */
 146                                 RAISES_EVENT(USB_DeviceUnattached);
 147
 148                                 /** This module raises the \ref USB_DeviceEnumerationFailed event when in host mode, and an
 149                                  *  attached USB device has failed to successfully enumerated.
 150                                  *
 151                                  *  \see \ref Group_Events for more information on this event.
 152                                  */
 153                                 RAISES_EVENT(USB_DeviceEnumerationFailed);
 154
 155                                 /** This module raises the \ref USB_DeviceEnumerationComplete event when in host mode, and an
 156                                  *  attached USB device has been successfully enumerated and ready to be used by the user
 157                                  *  application.
 158                                  *
 159                                  *  \see \ref Group_Events for more information on this event.
 160                                  */
 161                                 RAISES_EVENT(USB_DeviceEnumerationComplete);
 162
 163                                 /** This module raises the \ref USB_Disconnect event when an attached USB device is removed from the USB
 164                                  *  bus.
 165                                  *
 166                                  *  \see \ref Group_Events for more information on this event.
 167                                  */
 168                                 RAISES_EVENT(USB_Disconnect);
 169                         #endif
 170
 171                 /* Tasks: */
 172                         /** This is the main USB management task. The USB driver requires that this task be executed
 173                          *  continuously when the USB system is active (device attached in host mode, or attached to a host
 174                          *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,
 175                          *  scheduler (e.g. the simple LUFA Scheduler), fast timer ISR or the main user application loop.
 176                          *
 177                          *  The USB task must be serviced within 50mS in all modes, when needed. The task may be serviced
 178                          *  at all times, or (for minimum CPU consumption):
 179                          *
 180                          *    - In device mode, it may be disabled at start-up, enabled on the firing of the \ref USB_Connect event
 181                          *    and disabled again on the firing of the \ref USB_Disconnect event.
 182                          *
 183                          *    - In host mode, it may be disabled at start-up, enabled on the firing of the \ref USB_DeviceAttached
 184                          *    event and disabled again on the firing of the \ref USB_DeviceUnattached event.
 185                          *
 186                          *  \see \ref Group_Events for more information on the USB events.
 187                          *
 188                          *  \ingroup Group_USBManagement
 189                          */
 190                         TASK(USB_USBTask);
 191
 192         /* Private Interface - For use in library only: */
 193         #if !defined(__DOXYGEN__)
 194                 /* Function Prototypes: */
 195                         #if defined(INCLUDE_FROM_USBTASK_C)
 196                                 #if defined(USB_CAN_BE_HOST)
 197                                         static void USB_HostTask(void);
 198                                 #endif
 199
 200                                 #if defined(USB_CAN_BE_DEVICE)
 201                                         static void USB_DeviceTask(void);
 202                                 #endif
 203                         #endif
 204
 205                 /* Macros: */
 206                         #define HOST_TASK_NONBLOCK_WAIT(duration, nextstate) {USB_HostState = HOST_STATE_WaitForDevice; WaitMSRemaining = duration; PostWaitState = nextstate; }
 207         #endif
 208
 209         /* Disable C linkage for C++ Compilers: */
 210                 #if defined(__cplusplus)
 211                         }
 212                 #endif
 213
 214 #endif