git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Main USB service task management\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * Copyright(C) Dean Camera, 2011, 2012\r
   7  * All rights reserved.\r
   8  *\r
   9  * @par\r
  10  * Software that is described herein is for illustrative purposes only\r
  11  * which provides customers with programming information regarding the\r
  12  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  13  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  14  * all warranties, express or implied, including all implied warranties of\r
  15  * merchantability, fitness for a particular purpose and non-infringement of\r
  16  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  17  * or liability for the use of the software, conveys no license or rights under any\r
  18  * patent, copyright, mask work right, or any other intellectual property rights in\r
  19  * or to any products. NXP Semiconductors reserves the right to make changes\r
  20  * in the software without notification. NXP Semiconductors also makes no\r
  21  * representation or warranty that such application will be suitable for the\r
  22  * specified use without further testing or modification.\r
  23  *\r
  24  * @par\r
  25  * Permission to use, copy, modify, and distribute this software and its\r
  26  * documentation is hereby granted, under NXP Semiconductors' and its\r
  27  * licensor's relevant copyrights in the software, without fee, provided that it\r
  28  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  29  * copyright, permission, and disclaimer notice must appear in all copies of\r
  30  * this code.\r
  31  */\r
  32 \r
  33 \r
  34 #ifndef __USBTASK_H__\r
  35 #define __USBTASK_H__\r
  36 \r
  37         /* Includes: */\r
  38                 #include "../../../Common/Common.h"\r
  39                 #include "USBMode.h"            \r
  40                 #include "USBController.h"\r
  41                 #include "Events.h"\r
  42                 #include "StdRequestType.h"\r
  43                 #include "StdDescriptors.h"\r
  44 \r
  45                 #if defined(USB_CAN_BE_DEVICE)\r
  46                         #include "DeviceStandardReq.h"\r
  47                 #endif\r
  48 \r
  49                 #if defined(USB_CAN_BE_HOST)\r
  50                         #include "HostStandardReq.h"\r
  51                 #endif\r
  52 \r
  53         /* Enable C linkage for C++ Compilers: */\r
  54                 #if defined(__cplusplus)\r
  55                         extern "C" {\r
  56                 #endif\r
  57 \r
  58         /* Preprocessor Checks: */\r
  59                 #if !defined(__INCLUDE_FROM_USB_DRIVER)\r
  60                         #error Do not include this file directly. Include lpcroot/libraries/LPCUSBlib/Drivers/USB/USB.h instead.\r
  61                 #endif\r
  62 \r
  63         /* Public Interface - May be used in end-application: */\r
  64                 /* Global Variables: */\r
  65                         /** Indicates if the USB interface is currently initialized but not necessarily connected to a host\r
  66                          *  or device (i.e. if @ref USB_Init() has been run). If this is false, all other library globals related\r
  67                          *  to the USB driver are invalid.\r
  68                          *\r
  69                          *  @note This variable should be treated as read-only in the user application, and never manually\r
  70                          *        changed in value.\r
  71                          *\r
  72                          *  @ingroup Group_USBManagement\r
  73                          */\r
  74                         extern volatile bool USB_IsInitialized;\r
  75 \r
  76                         /** Structure containing the last received Control request when in Device mode (for use in user-applications\r
  77                          *  inside of the @ref EVENT_USB_Device_ControlRequest() event, or for filling up with a control request to \r
  78                          *  issue when in Host mode before calling @ref USB_Host_SendControlRequest().\r
  79                          *\r
  80                          *  @note The contents of this structure is automatically endian-corrected for the current CPU architecture.\r
  81                          *\r
  82                          *  @ingroup Group_USBManagement\r
  83                          */\r
  84                          extern USB_Request_Header_t USB_ControlRequest;\r
  85 \r
  86                         #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)\r
  87                                 #if !defined(HOST_STATE_AS_GPIOR) || defined(__DOXYGEN__)\r
  88                                         /** Indicates the current host state machine state. When in host mode, this indicates the state\r
  89                                          *  via one of the values of the @ref USB_Host_States_t enum values.\r
  90                                          *\r
  91                                          *  This value should not be altered by the user application as it is handled automatically by the\r
  92                                          *  library.\r
  93                                          *\r
  94                                          *  To reduce program size and speed up checks of this global on the LPC architecture, it can be\r
  95                                          *  placed into one of the LPC's \c GPIOR hardware registers instead of RAM by defining the\r
  96                                          *  \c HOST_STATE_AS_GPIOR token to a value between 0 and 2 in the project makefile and passing it to\r
  97                                          *  the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used\r
  98                                          *  in the user application except implicitly via the library APIs.\r
  99                                          *\r
 100                                          *  @note This global is only present if the user application can be a USB host.\r
 101                                          *\r
 102                                          *  @see @ref USB_Host_States_t for a list of possible device states.\r
 103                                          *\r
 104                                          *  @ingroup Group_Host\r
 105                                          */\r
 106                                         extern volatile uint8_t USB_HostState[MAX_USB_CORE];\r
 107                                 #else\r
 108                                         #define _GET_HOST_GPIOR_NAME2(y) GPIOR ## y\r
 109                                         #define _GET_HOST_GPIOR_NAME(x)  _GET_HOST_GPIOR_NAME2(x)\r
 110                                         #define USB_HostState            _GET_HOST_GPIOR_NAME(HOST_STATE_AS_GPIOR)\r
 111                                 #endif\r
 112                         #endif\r
 113 \r
 114                         #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)\r
 115                                 #if !defined(DEVICE_STATE_AS_GPIOR) || defined(__DOXYGEN__)\r
 116                                         /** Indicates the current device state machine state. When in device mode, this indicates the state\r
 117                                          *  via one of the values of the @ref USB_Device_States_t enum values.\r
 118                                          *\r
 119                                          *  This value should not be altered by the user application as it is handled automatically by the\r
 120                                          *  library. The only exception to this rule is if the NO_LIMITED_CONTROLLER_CONNECT token is used\r
 121                                          *  (see @ref EVENT_USB_Device_Connect() and @ref EVENT_USB_Device_Disconnect() events).\r
 122                                          *\r
 123                                          *  To reduce program size and speed up checks of this global on the LPC architecture, it can be\r
 124                                          *  placed into one of the LPC's \c GPIOR hardware registers instead of RAM by defining the\r
 125                                          *  \c DEVICE_STATE_AS_GPIOR token to a value between 0 and 2 in the project makefile and passing it to\r
 126                                          *  the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used\r
 127                                          *  in the user application except implicitly via the library APIs.\r
 128                                          *\r
 129                                          *  @note This global is only present if the user application can be a USB device.\r
 130                                          *        \n\n\r
 131                                          *\r
 132                                          *  @note This variable should be treated as read-only in the user application, and never manually\r
 133                                          *        changed in value except in the circumstances outlined above.\r
 134                                          *\r
 135                                          *  @see @ref USB_Device_States_t for a list of possible device states.\r
 136                                          *\r
 137                                          *  @ingroup Group_Device\r
 138                                          */\r
 139                                         extern volatile uint8_t USB_DeviceState[];\r
 140                                 #else\r
 141                                         #define _GET_DEVICE_GPIOR_NAME2(y) GPIOR ## y\r
 142                                         #define _GET_DEVICE_GPIOR_NAME(x)  _GET_DEVICE_GPIOR_NAME2(x)\r
 143                                         #define USB_DeviceState[0]            _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR)\r
 144                                         #define USB_DeviceState[1]            _GET_DEVICE_GPIOR_NAME(DEVICE_STATE_AS_GPIOR)\r
 145                                 #endif\r
 146                         #endif\r
 147 \r
 148                 /* Function Prototypes: */\r
 149                         /** This is the main USB management task. The USB driver requires this task to be executed\r
 150                          *  continuously when the USB system is active (device attached in host mode, or attached to a host\r
 151                          *  in device mode) in order to manage USB communications. This task may be executed inside an RTOS,\r
 152                          *  fast timer ISR or the main user application loop.\r
 153                          *\r
 154                          *  The USB task must be serviced within 30ms while in device mode, or within 1ms while in host mode.\r
 155                          *  The task may be serviced at all times, or (for minimum CPU consumption):\r
 156                          *\r
 157                          *    - In device mode, it may be disabled at start-up, enabled on the firing of the @ref EVENT_USB_Device_Connect()\r
 158                          *      event and disabled again on the firing of the @ref EVENT_USB_Device_Disconnect() event.\r
 159                          *\r
 160                          *    - In host mode, it may be disabled at start-up, enabled on the firing of the @ref EVENT_USB_Host_DeviceAttached()\r
 161                          *      event and disabled again on the firing of the @ref EVENT_USB_Host_DeviceEnumerationComplete() or\r
 162                          *      @ref EVENT_USB_Host_DeviceEnumerationFailed() events.\r
 163                          *\r
 164                          *  If in device mode (only), the control endpoint can instead be managed via interrupts entirely by the library\r
 165                          *  by defining the INTERRUPT_CONTROL_ENDPOINT token and passing it to the compiler via the -D switch.\r
 166                          *\r
 167                          *  @see @ref Group_Events for more information on the USB events.\r
 168                          *\r
 169                          *  @ingroup Group_USBManagement\r
 170                          */\r
 171                         void USB_USBTask(uint8_t corenum, uint8_t mode);\r
 172 \r
 173         /* Private Interface - For use in library only: */\r
 174         #if !defined(__DOXYGEN__)\r
 175                 /* Function Prototypes: */\r
 176                         #if defined(__INCLUDE_FROM_USBTASK_C)\r
 177                                 #if defined(USB_CAN_BE_HOST)\r
 178                                         static void USB_HostTask(uint8_t corenum);\r
 179                                 #endif\r
 180 \r
 181                                 #if defined(USB_CAN_BE_DEVICE)\r
 182                                         static void USB_DeviceTask(uint8_t corenum);\r
 183                                 #endif\r
 184                         #endif\r
 185 \r
 186                 /* Macros: */\r
 187                         #define HOST_TASK_NONBLOCK_WAIT(CoreID, Duration, NextState) MACROS{ USB_HostState[(CoreID)]   = HOST_STATE_WaitForDevice; \\r
 188                                                                                      WaitMSRemaining = (Duration);               \\r
 189                                                                                      PostWaitState   = (NextState);              }MACROE\r
 190         #endif\r
 191 \r
 192         /* Disable C linkage for C++ Compilers: */\r
 193                 #if defined(__cplusplus)\r
 194                         }\r
 195                 #endif\r
 196 \r
 197 #endif\r
 198 \r