LUFA/Drivers/USB/HighLevel/USBTask.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2010.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2010  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 <avr/io.h>
  46                 #include <avr/interrupt.h>
  47                 #include <stdbool.h>
  48
  49                 #include "../LowLevel/LowLevel.h"
  50                 #include "Events.h"
  51                 #include "StdRequestType.h"
  52                 #include "StdDescriptors.h"
  53                 #include "USBMode.h"
  54
  55                 #if defined(USB_CAN_BE_DEVICE)
  56                         #include "../LowLevel/DevChapter9.h"
  57                 #endif
  58
  59                 #if defined(USB_CAN_BE_HOST)
  60                         #include "../LowLevel/HostChapter9.h"
  61                 #endif
  62
  63         /* Enable C linkage for C++ Compilers: */
  64                 #if defined(__cplusplus)
  65                         extern "C" {
  66                 #endif
  67
  68         /* Preprocessor Checks: */
  69                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  70                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  71                 #endif
  72
  73         /* Public Interface - May be used in end-application: */
  74                 /* Global Variables: */
  75                         /** Indicates if the USB interface is currently initialized but not necessarily connected to a host
  76                          *  or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals are invalid.
  77                          *
  78                          *  \note This variable should be treated as read-only in the user application, and never manually
  79                          *        changed in value.
  80                          *
  81                          *  \ingroup Group_USBManagement
  82                          */
  83                         extern volatile bool USB_IsInitialized;
  84
  85                         /** Structure containing the last received Control request when in Device mode (for use in user-applications
  86                          *  inside of the \ref EVENT_USB_Device_UnhandledControlRequest() event, or for filling up with a control request to issue when
  87                          *  in Host mode before calling \ref USB_Host_SendControlRequest().
  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 may be altered by the user application to implement the \ref HOST_STATE_Addressed,
  99                                          *  \ref HOST_STATE_Configured and \ref HOST_STATE_Suspended states which are not implemented by
 100                                          *  the library.
 101                                          *
 102                                          *  To reduce program size and speed up checks of this global, it can be placed into one of the AVR's
 103                                          *  GPIOR hardware registers instead of RAM by defining the HOST_STATE_AS_GPIOR token to a value
 104                                          *  between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When
 105                                          *  defined, the corresponding GPIOR register should not be used in the user application except
 106                                          *  implicitly via the library APIs.
 107                                          *
 108                                          *  \note This global is only present if the user application can be a USB host.
 109                                          *
 110                                          *  \see \ref USB_Host_States_t for a list of possible device states
 111                                          *
 112                                          *  \ingroup Group_Host
 113                                          */
 114                                         extern volatile uint8_t USB_HostState;
 115                                 #else
 116                                         #define _GET_HOST_GPIOR_NAME2(y) GPIOR ## y
 117                                         #define _GET_HOST_GPIOR_NAME(x)  _GET_HOST_GPIOR_NAME2(x)
 118                                         #define USB_HostState            _GET_HOST_GPIOR_NAME(HOST_STATE_AS_GPIOR)
 119                                 #endif
 120                         #endif
 121
 122                         #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)
 123                                 #if !defined(DEVICE_STATE_AS_GPIOR) || defined(__DOXYGEN__)
 124                                         /** Indicates the current device state machine state. When in device mode, this indicates the state
 125                                          *  via one of the values of the \ref USB_Device_States_t enum values.
 126                                          *
 127                                          *  This value should not be altered by the user application as it is handled automatically by the
 128                                          *  library. The only exception to this rule is if the NO_LIMITED_CONTROLLER_CONNECT token is used
 129                                          *  (see \ref EVENT_USB_Device_Connect() and \ref EVENT_USB_Device_Disconnect() events).
 130                                          *
 131                                          *  To reduce program size and speed up checks of this global, it can be placed into one of the AVR's
 132                                          *  GPIOR hardware registers instead of RAM by defining the DEVICE_STATE_AS_GPIOR token to a value
 133                                          *  between 0 and 2 in the project makefile and passing it to the compiler via the -D switch. When
 134                                          *  defined, the corresponding GPIOR register should not be used in the user application except
 135                                          *  implicitly via the library APIs.
 136                                          *
 137                                          *  \note This global is only present if the user application can be a USB device.
 138                                          *        \n\n
 139                                          *
 140                                          *  \note This variable should be treated as read-only in the user application, and never manually
 141                                          *        changed in value except in the circumstances outlined above.
 142                                          *
 143                                          *  \see \ref USB_Device_States_t for a list of possible device states
 144                                          *
 145                                          *  \ingroup Group_Device
 146                                          */
 147                                         extern volatile uint8_t USB_DeviceState;
 148                                 #else
 149                                         #define _GET_DEVICE_GPIOR_NAME2(y) GPIOR ## y
 150                                         #define _GET_DEVICE_GPIOR_NAME(x)  _GET_DEVICE_GPIOR_NAME2(x)
 151                                         #define USB_DeviceState            _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR)
 152                                 #endif
 153                         #endif
 154
 155                 /* Function Prototypes: */
 156                         /** This is the main USB management task. The USB driver requires that this task be executed
 157                          *  continuously when the USB system is active (device attached in host mode, or attached to a host
 158                          *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,
 159                          *  fast timer ISR or the main user application loop.
 160                          *
 161                          *  The USB task must be serviced within 30ms while in device mode, or within 1ms while in host mode.
 162                          *  The task may be serviced at all times, or (for minimum CPU consumption):
 163                          *
 164                          *    - In device mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Device_Connect()
 165                          *      event and disabled again on the firing of the \ref EVENT_USB_Device_Disconnect() event.
 166                          *
 167                          *    - In host mode, it may be disabled at start-up, enabled on the firing of the \ref EVENT_USB_Host_DeviceAttached()
 168                          *      event and disabled again on the firing of the \ref EVENT_USB_Host_DeviceEnumerationComplete() or
 169                          *      \ref EVENT_USB_Host_DeviceEnumerationFailed() events.
 170                          *
 171                          *  If in device mode (only), the control endpoint can instead be managed via interrupts entirely by the library
 172                          *  by defining the INTERRUPT_CONTROL_ENDPOINT token and passing it to the compiler via the -D switch.
 173                          *
 174                          *  \see \ref Group_Events for more information on the USB events.
 175                          *
 176                          *  \ingroup Group_USBManagement
 177                          */
 178                         void USB_USBTask(void);
 179
 180         /* Private Interface - For use in library only: */
 181         #if !defined(__DOXYGEN__)
 182                 /* Function Prototypes: */
 183                         #if defined(__INCLUDE_FROM_USBTASK_C)
 184                                 #if defined(USB_CAN_BE_HOST)
 185                                         static void USB_HostTask(void);
 186                                 #endif
 187
 188                                 #if defined(USB_CAN_BE_DEVICE)
 189                                         static void USB_DeviceTask(void);
 190                                 #endif
 191                         #endif
 192
 193                 /* Macros: */
 194                         #define HOST_TASK_NONBLOCK_WAIT(duration, nextstate) MACROS{ USB_HostState = HOST_STATE_WaitForDevice; \
 195                                                                                      WaitMSRemaining = (duration);             \
 196                                                                                      PostWaitState = (nextstate);        }MACROE
 197         #endif
 198
 199         /* Disable C linkage for C++ Compilers: */
 200                 #if defined(__cplusplus)
 201                         }
 202                 #endif
 203
 204 #endif