git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Common USB Host definitions for all architectures\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 /** @ingroup Group_USB\r
  34  *  @defgroup Group_Host Host Management\r
  35  *  @brief USB Host management definitions for USB host mode.\r
  36  *\r
  37  *  USB Host mode related macros and enums. This module contains macros and enums which are used when\r
  38  *  the USB controller is initialized in host mode.\r
  39  *\r
  40  *  @{\r
  41  */\r
  42 \r
  43 #ifndef __USBHOST_H__\r
  44 #define __USBHOST_H__\r
  45 \r
  46         /* Includes: */\r
  47                 #include "../../../Common/Common.h"\r
  48                 #include "USBMode.h"            \r
  49 \r
  50         /* Enable C linkage for C++ Compilers: */\r
  51                 #if defined(__cplusplus)\r
  52                         extern "C" {\r
  53                 #endif\r
  54 \r
  55         /* Preprocessor Checks: */\r
  56                 #if !defined(__INCLUDE_FROM_USB_DRIVER)\r
  57                         #error Do not include this file directly. Include lpcroot/libraries/LPCUSBlib/Drivers/USB/USB.h instead.\r
  58                 #endif\r
  59 \r
  60         /* Public Interface - May be used in end-application: */\r
  61                 /* Enums: */\r
  62                         /** Enum for the various states of the USB Host state machine.\r
  63                          *\r
  64                          *  For information on each possible USB host state, refer to the USB 2.0 specification.\r
  65                          *  Several of the USB host states are broken up further into multiple smaller sub-states,\r
  66                          *  so that they can be internally implemented inside the library in an efficient manner.\r
  67                          *\r
  68                          *  @see @ref USB_HostState, which stores the current host state machine state.\r
  69                          */\r
  70                         enum USB_Host_States_t\r
  71                         {\r
  72                                 HOST_STATE_WaitForDevice                = 0,  /**< This state indicates that the stack is waiting for an interval\r
  73                                                                                *   to elapse before continuing with the next step of the device\r
  74                                                                                *   enumeration process.\r
  75                                                                                */\r
  76                                 HOST_STATE_Unattached                   = 1,  /**< This state indicates that the host state machine is waiting for\r
  77                                                                                *   a device to be attached so that it can start the enumeration process.\r
  78                                                                                */\r
  79                                 HOST_STATE_Powered                      = 2,  /**< This state indicates that a device has been attached, and the\r
  80                                                                                *   library's internals are being configured to begin the enumeration\r
  81                                                                                *   process.\r
  82                                                                                */\r
  83                                 HOST_STATE_Powered_WaitForDeviceSettle  = 3,  /**< This state indicates that the stack is waiting for the initial\r
  84                                                                                *   settling period to elapse before beginning the enumeration process.\r
  85                                                                                */\r
  86                                 HOST_STATE_Powered_WaitForConnect       = 4,  /**< This state indicates that the stack is waiting for a connection event\r
  87                                                                                *   from the USB controller to indicate a valid USB device has been attached\r
  88                                                                                *   to the bus and is ready to be enumerated.\r
  89                                                                                */\r
  90                                 HOST_STATE_Powered_DoReset              = 5,  /**< This state indicates that a valid USB device has been attached, and that\r
  91                                                                                *   it will now be reset to ensure it is ready for enumeration.\r
  92                                                                                */\r
  93                                 HOST_STATE_Powered_ConfigPipe           = 6,  /**< This state indicates that the attached device is currently powered and\r
  94                                                                                *   reset, and that the control pipe is now being configured by the stack.\r
  95                                                                                */\r
  96                                 HOST_STATE_Default                      = 7,  /**< This state indicates that the stack is currently retrieving the control\r
  97                                                                                *   endpoint's size from the device, so that the control pipe can be altered\r
  98                                                                                *   to match.\r
  99                                                                                */\r
 100                                 HOST_STATE_Default_PostReset            = 8,  /**< This state indicates that the control pipe is being reconfigured to match\r
 101                                                                                *   the retrieved control endpoint size from the device, and the device's USB\r
 102                                                                                *   bus address is being set.\r
 103                                                                                */\r
 104                                 HOST_STATE_Default_PostAddressSet       = 9,  /**< This state indicates that the device's address has now been set, and the\r
 105                                                                                *   stack is has now completed the device enumeration process. This state causes \r
 106                                                                                *   the stack to change the current USB device address to that set for the\r
 107                                                                                *   connected device, before progressing to the @ref HOST_STATE_Addressed state\r
 108                                                                                *   ready for use in the user application.\r
 109                                                                                */\r
 110                                 HOST_STATE_Addressed                    = 10, /**< Indicates that the device has been enumerated and addressed, and is now waiting\r
 111                                                                                *   for the user application to configure the device ready for use.                              \r
 112                                                                                */\r
 113                                 HOST_STATE_Configured                   = 11, /**< Indicates that the device has been configured into a valid device configuration,\r
 114                                                                                *   ready for general use by the user application.                               \r
 115                                                                                */\r
 116                         };\r
 117 \r
 118                 #include "StdDescriptors.h"\r
 119                 #include "Pipe.h"\r
 120                 #include "USBInterrupt.h"\r
 121                 \r
 122                 /* Macros: */\r
 123                 /** Indicates the fixed USB device address which any attached device is enumerated to when in\r
 124                  *  host mode. As only one USB device may be attached to the LPC in host mode at any one time\r
 125                  *  and that the address used is not important (other than the fact that it is non-zero), a\r
 126                  *  fixed value is specified by the library.\r
 127                  */\r
 128                                         #define USB_HOST_DEVICEADDRESS                 1\r
 129 \r
 130                                         #if !defined(USB_HOST_TIMEOUT_MS) || defined(__DOXYGEN__)\r
 131                 /** Constant for the maximum software timeout period of sent USB control transactions to an attached\r
 132                  *  device. If a device fails to respond to a sent control request within this period, the\r
 133                  *  library will return a timeout error code.\r
 134                  *\r
 135                  *  This value may be overridden in the user project makefile as the value of the\r
 136                  *  @ref USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch.\r
 137                  */\r
 138                                                 #define USB_HOST_TIMEOUT_MS                1000\r
 139                                         #endif\r
 140 \r
 141                                         #if !defined(HOST_DEVICE_SETTLE_DELAY_MS) || defined(__DOXYGEN__)\r
 142                 /** Constant for the delay in milliseconds after a device is connected before the library\r
 143                  *  will start the enumeration process. Some devices require a delay of up to 5 seconds\r
 144                  *  after connection before the enumeration process can start or incorrect operation will\r
 145                  *  occur.\r
 146                  *\r
 147                  *  The default delay value may be overridden in the user project makefile by defining the\r
 148                  *  \c HOST_DEVICE_SETTLE_DELAY_MS token to the required delay in milliseconds, and passed to the\r
 149                  *  compiler using the -D switch.\r
 150                  */\r
 151                                                 #define HOST_DEVICE_SETTLE_DELAY_MS        1000\r
 152                                         #endif\r
 153 \r
 154                 /** Enum for the error codes for the @ref EVENT_USB_Host_HostError() event.\r
 155                  *\r
 156                  *  @see @ref Group_Events for more information on this event.\r
 157                  */\r
 158                 enum USB_Host_ErrorCodes_t {\r
 159                         HOST_ERROR_VBusVoltageDip       = 0,                    /**< VBUS voltage dipped to an unacceptable level. This\r
 160                                                                                                                          *   error may be the result of an attached device drawing\r
 161                                                                                                                          *   too much current from the VBUS line, or due to the\r
 162                                                                                                                          *   LPC's power source being unable to supply sufficient\r
 163                                                                                                                          *   current.\r
 164                                                                                                                          */\r
 165                 };\r
 166 \r
 167                 /** Enum for the error codes for the @ref EVENT_USB_Host_DeviceEnumerationFailed() event.\r
 168                  *\r
 169                  *  @see @ref Group_Events for more information on this event.\r
 170                  */\r
 171                 enum USB_Host_EnumerationErrorCodes_t {\r
 172                         HOST_ENUMERROR_NoError          = 0,                    /**< No error occurred. Used internally, this is not a valid\r
 173                                                                                                                          *   ErrorCode parameter value for the @ref EVENT_USB_Host_DeviceEnumerationFailed()\r
 174                                                                                                                          *   event.\r
 175                                                                                                                          */\r
 176                         HOST_ENUMERROR_WaitStage        = 1,                    /**< One of the delays between enumeration steps failed\r
 177                                                                                                                          *   to complete successfully, due to a timeout or other\r
 178                                                                                                                          *   error.\r
 179                                                                                                                          */\r
 180                         HOST_ENUMERROR_NoDeviceDetected = 2,                    /**< No device was detected, despite the USB data lines\r
 181                                                                                                                          *   indicating the attachment of a device.\r
 182                                                                                                                          */\r
 183                         HOST_ENUMERROR_ControlError     = 3,                    /**< One of the enumeration control requests failed to\r
 184                                                                                                                          *   complete successfully.\r
 185                                                                                                                          */\r
 186                         HOST_ENUMERROR_PipeConfigError  = 4,                    /**< The default control pipe (address 0) failed to\r
 187                                                                                                                          *   configure correctly.\r
 188                                                                                                                          */\r
 189                 };\r
 190 \r
 191                 /**\r
 192                  * @brief  Get current active host core number\r
 193                  * @return Active USB host core number\r
 194                  */\r
 195                 uint8_t USB_Host_GetActiveHost(void);\r
 196 \r
 197                 /** Array stores pre-set size of control pipe of all available USB cores\r
 198                  */\r
 199                 extern uint8_t USB_Host_ControlPipeSize[MAX_USB_CORE];\r
 200 \r
 201                 /* Inline Functions: */\r
 202                                         #if !defined(NO_SOF_EVENTS)\r
 203 \r
 204                 /**\r
 205                  * @brief  Enables the host mode Start Of Frame events. When enabled, this causes the\r
 206                  *  @ref EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,\r
 207                  *  at the start of each USB frame when a device is enumerated while in host mode.\r
 208                  *\r
 209                  *  @note Not available when the \c NO_SOF_EVENTS compile time token is defined.\r
 210                  * @return Nothing\r
 211                  */\r
 212                 static inline void USB_Host_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;\r
 213 \r
 214                 static inline void USB_Host_EnableSOFEvents(void)\r
 215                 {}\r
 216 \r
 217                 /**\r
 218                  * @brief  Disables the host mode Start Of Frame events. When disabled, this stops the firing of the\r
 219                  *  @ref EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.\r
 220                  *\r
 221                  *  @note Not available when the NO_SOF_EVENTS compile time token is defined.\r
 222                  * @return Nothing\r
 223                  */\r
 224                 static inline void USB_Host_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;\r
 225 \r
 226                 static inline void USB_Host_DisableSOFEvents(void)\r
 227                 {}\r
 228 \r
 229                                         #endif\r
 230 \r
 231                 /**\r
 232                  * @brief  Resets the USB bus, including the endpoints in any attached device and pipes on the LPC host.\r
 233                  *  USB bus resets leave the default control pipe configured (if already configured).\r
 234                  *\r
 235                  *  If the USB bus has been suspended prior to issuing a bus reset, the attached device will be\r
 236                  *  woken up automatically and the bus resumed after the reset has been correctly issued.\r
 237                  * @return Nothing\r
 238                  */\r
 239                 static inline void USB_Host_ResetBus(void) ATTR_ALWAYS_INLINE;\r
 240 \r
 241                 static inline void USB_Host_ResetBus(void)\r
 242                 {}\r
 243 \r
 244                 /**\r
 245                  * @brief  Determines if a previously issued bus reset (via the @ref USB_Host_ResetBus() macro) has\r
 246                  *  completed.\r
 247                  * @return Boolean \c true if no bus reset is currently being sent, \c false otherwise.\r
 248                  */\r
 249                 static inline bool USB_Host_IsBusResetComplete(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 250 \r
 251                 static inline bool USB_Host_IsBusResetComplete(void)\r
 252                 {\r
 253                         return true;\r
 254                 }\r
 255 \r
 256                 /**\r
 257                  * @brief  Resumes USB communications with an attached and enumerated device, by resuming the transmission\r
 258                  *  of the 1MS Start Of Frame messages to the device. When resumed, USB communications between the\r
 259                  *  host and attached device may occur.\r
 260                  * @return Nothing\r
 261                  */\r
 262                 static inline void USB_Host_ResumeBus(void) ATTR_ALWAYS_INLINE;\r
 263 \r
 264                 static inline void USB_Host_ResumeBus(void)\r
 265                 {}\r
 266 \r
 267                 /**\r
 268                  * @brief  Suspends the USB bus, preventing any communications from occurring between the host and attached\r
 269                  *  device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame\r
 270                  *  messages to the device.\r
 271                  * @return Nothing\r
 272                  */\r
 273                 static inline void USB_Host_SuspendBus(void) ATTR_ALWAYS_INLINE;\r
 274 \r
 275                 static inline void USB_Host_SuspendBus(void)\r
 276                 {}\r
 277 \r
 278                 /**\r
 279                  * @brief  Determines if the USB bus has been suspended via the use of the @ref USB_Host_SuspendBus() macro,\r
 280                  *  false otherwise. While suspended, no USB communications can occur until the bus is resumed,\r
 281                  *  except for the Remote Wakeup event from the device if supported.\r
 282                  *\r
 283                  * @return Boolean \c true if the bus is currently suspended, \c false otherwise.\r
 284                  */\r
 285                 static inline bool USB_Host_IsBusSuspended(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 286 \r
 287                 static inline bool USB_Host_IsBusSuspended(void)\r
 288                 {\r
 289                         return false;\r
 290                 }\r
 291 \r
 292                 /**\r
 293                  * @brief  Determines if the attached device is currently enumerated in Full Speed mode (12Mb/s), or\r
 294                  *  false if the attached device is enumerated in Low Speed mode (1.5Mb/s).\r
 295                  *\r
 296                  * @return Boolean \c true if the attached device is enumerated in Full Speed mode, \c false otherwise.\r
 297                  */\r
 298                 static inline bool USB_Host_IsDeviceFullSpeed(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 299 \r
 300                 static inline bool USB_Host_IsDeviceFullSpeed(void)\r
 301                 {\r
 302                         return true;                    // implement later when needed\r
 303                 }\r
 304 \r
 305                 /**\r
 306                  * @brief  Determines if the attached device is currently issuing a Remote Wakeup request, requesting\r
 307                  *  that the host resume the USB bus and wake up the device, false otherwise.\r
 308                  *\r
 309                  * @return Boolean \c true if the attached device has sent a Remote Wakeup request, \c false otherwise.\r
 310                   */\r
 311                 static inline bool USB_Host_IsRemoteWakeupSent(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 312 \r
 313                 static inline bool USB_Host_IsRemoteWakeupSent(void)\r
 314                 {\r
 315                         return false;\r
 316                 }\r
 317 \r
 318                 /** Clears the flag indicating that a Remote Wakeup request has been issued by an attached device. */\r
 319                 static inline void USB_Host_ClearRemoteWakeupSent(void) ATTR_ALWAYS_INLINE;\r
 320 \r
 321                 static inline void USB_Host_ClearRemoteWakeupSent(void)\r
 322                 {}\r
 323 \r
 324                 /** Accepts a Remote Wakeup request from an attached device. This must be issued in response to\r
 325                  *  a device's Remote Wakeup request within 2ms for the request to be accepted and the bus to\r
 326                  *  be resumed.\r
 327                  */\r
 328                 static inline void USB_Host_ResumeFromWakeupRequest(void) ATTR_ALWAYS_INLINE;\r
 329 \r
 330                 static inline void USB_Host_ResumeFromWakeupRequest(void)\r
 331                 {}\r
 332 \r
 333                 /**\r
 334                  * @brief  Determines if a resume from Remote Wakeup request is currently being sent to an attached\r
 335                  *  device.\r
 336                  *\r
 337                  *  @return Boolean \c true if no resume request is currently being sent, \c false otherwise.\r
 338                  */\r
 339                 static inline bool USB_Host_IsResumeFromWakeupRequestSent(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 340 \r
 341                 static inline bool USB_Host_IsResumeFromWakeupRequestSent(void)\r
 342                 {\r
 343                         return false;\r
 344                 }\r
 345 \r
 346                 /* Private Interface - For use in library only: */\r
 347                         #if !defined(__DOXYGEN__)\r
 348                 /* Macros: */\r
 349                 static inline void USB_Host_HostMode_On(void) ATTR_ALWAYS_INLINE;\r
 350 \r
 351                 static inline void USB_Host_HostMode_On(void)\r
 352                 {}\r
 353 \r
 354                 static inline void USB_Host_HostMode_Off(void) ATTR_ALWAYS_INLINE;\r
 355 \r
 356                 static inline void USB_Host_HostMode_Off(void)\r
 357                 {}\r
 358 \r
 359                 static inline void USB_Host_VBUS_Auto_Enable(void) ATTR_ALWAYS_INLINE;\r
 360 \r
 361                 static inline void USB_Host_VBUS_Auto_Enable(void)\r
 362                 {}\r
 363 \r
 364                 static inline void USB_Host_VBUS_Manual_Enable(void) ATTR_ALWAYS_INLINE;\r
 365 \r
 366                 static inline void USB_Host_VBUS_Manual_Enable(void)\r
 367                 {}\r
 368 \r
 369                 static inline void USB_Host_VBUS_Auto_On(void) ATTR_ALWAYS_INLINE;\r
 370 \r
 371                 static inline void USB_Host_VBUS_Auto_On(void)\r
 372                 {}\r
 373 \r
 374                 static inline void USB_Host_VBUS_Manual_On(void) ATTR_ALWAYS_INLINE;\r
 375 \r
 376                 static inline void USB_Host_VBUS_Manual_On(void)\r
 377                 {}\r
 378 \r
 379                 static inline void USB_Host_VBUS_Auto_Off(void) ATTR_ALWAYS_INLINE;\r
 380 \r
 381                 static inline void USB_Host_VBUS_Auto_Off(void)\r
 382                 {}\r
 383 \r
 384                 static inline void USB_Host_VBUS_Manual_Off(void) ATTR_ALWAYS_INLINE;\r
 385 \r
 386                 static inline void USB_Host_VBUS_Manual_Off(void)\r
 387                 {}\r
 388 \r
 389                 static inline void USB_Host_SetDeviceAddress(const uint8_t Address) ATTR_ALWAYS_INLINE;\r
 390 \r
 391                 static inline void USB_Host_SetDeviceAddress(const uint8_t Address)\r
 392                 {}\r
 393 \r
 394                 /* Enums: */\r
 395                 /** Enum defines error codes returned by \ref USB_Host_WaitMS()\r
 396                  */\r
 397                 enum USB_Host_WaitMSErrorCodes_t {\r
 398                         HOST_WAITERROR_Successful       = 0,\r
 399                         HOST_WAITERROR_DeviceDisconnect = 1,\r
 400                         HOST_WAITERROR_PipeError        = 2,\r
 401                         HOST_WAITERROR_SetupStalled     = 3,\r
 402                 };\r
 403 \r
 404                 /* Function Prototypes: */\r
 405                 /**\r
 406                  * @brief Perform enumeration process\r
 407                  *\r
 408                  * @param corenum: active USB port number\r
 409                  * @return Nothing\r
 410                  */\r
 411                 void    USB_Host_ProcessNextHostState(uint8_t corenum);\r
 412 \r
 413                 /**\r
 414                  * @brief A delay function use in host\r
 415                  * @note This function currently is not inplemented\r
 416                  * @return always return HOST_WAITERROR_Successful \ref USB_Host_WaitMSErrorCodes_t\r
 417                  */\r
 418                 uint8_t USB_Host_WaitMS(uint8_t MS);\r
 419 \r
 420                 /**\r
 421                  * @brief Returns the current USB frame number, when in host mode. Every millisecond the USB bus is active (i.e. not suspended)\r
 422                  *        the frame number is incremented by one.\r
 423                  * @return Current frame number on active USB port\r
 424                  */\r
 425                 uint16_t USB_Host_GetFrameNumber(void);\r
 426 \r
 427                                         #if defined(__INCLUDE_FROM_HOST_C)\r
 428                 // static void USB_Host_ResetDevice(void);\r
 429                                         #endif\r
 430                         #endif\r
 431 \r
 432 \r
 433         /* Disable C linkage for C++ Compilers: */\r
 434                 #if defined(__cplusplus)\r
 435                         }\r
 436                 #endif\r
 437 \r
 438 #endif\r
 439 \r
 440 /** @} */\r
 441 \r