git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Common USB Controller 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_USBManagement USB Interface Management\r
  35  *  @brief USB Controller definitions for general USB controller management.\r
  36  *\r
  37  *  Functions, macros, variables, enums and types related to the setup and management of the USB interface.\r
  38  *\r
  39  *  @{\r
  40  */\r
  41 \r
  42 #ifndef __USBCONTROLLER_H__\r
  43 #define __USBCONTROLLER_H__\r
  44 \r
  45         /* Includes: */\r
  46                 #include "../../../Common/Common.h"\r
  47                 #include "USBMode.h"            \r
  48 \r
  49         /* Enable C linkage for C++ Compilers: */\r
  50                 #if defined(__cplusplus)\r
  51                         extern "C" {\r
  52                 #endif\r
  53 \r
  54         /* Preprocessor Checks and Defines: */\r
  55                 #if !defined(__INCLUDE_FROM_USB_DRIVER)\r
  56                         #error Do not include this file directly. Include lpcroot/libraries/LPCUSBlib/Drivers/USB/USB.h instead.\r
  57                 #endif\r
  58 \r
  59         /* Defines: */\r
  60                 /** \name Endpoint Direction Masks */\r
  61                 //@{\r
  62                 /** Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's\r
  63                  *  direction for comparing with the \c ENDPOINT_DIR_* masks.\r
  64                  */\r
  65                 #define ENDPOINT_DIR_MASK                       0x80\r
  66 \r
  67                 /** Endpoint address direction mask for an OUT direction (Host to Device) endpoint. This may be ORed with\r
  68                  *  the index of the address within a device to obtain the full endpoint address.\r
  69                  */\r
  70                 #define ENDPOINT_DIR_OUT                        0x00\r
  71 \r
  72                 /** Endpoint address direction mask for an IN direction (Device to Host) endpoint. This may be ORed with\r
  73                  *  the index of the address within a device to obtain the full endpoint address.\r
  74                  */\r
  75                 #define ENDPOINT_DIR_IN                         0x80\r
  76                 //@}\r
  77 \r
  78                 /** \name Endpoint/Pipe Type Masks */\r
  79                 //@{\r
  80                 /** Mask for determining the type of an endpoint from an endpoint descriptor. This should then be compared\r
  81                  *  with the \c EP_TYPE_* masks to determine the exact type of the endpoint.\r
  82                  */\r
  83                 #define EP_TYPE_MASK                       0x03\r
  84 \r
  85                 /** Mask for a CONTROL type endpoint or pipe.\r
  86                  *\r
  87                  *  @note See @ref Group_EndpointManagement and @ref Group_PipeManagement for endpoint/pipe functions.\r
  88                  */\r
  89                 #define EP_TYPE_CONTROL                    0x00\r
  90 \r
  91                 /** Mask for an ISOCHRONOUS type endpoint or pipe.\r
  92                  *\r
  93                  *  @note See @ref Group_EndpointManagement and @ref Group_PipeManagement for endpoint/pipe functions.\r
  94                  */\r
  95                 #define EP_TYPE_ISOCHRONOUS                0x01\r
  96 \r
  97                 /** Mask for a BULK type endpoint or pipe.\r
  98                  *\r
  99                  *  @note See @ref Group_EndpointManagement and @ref Group_PipeManagement for endpoint/pipe functions.\r
 100                  */\r
 101                 #define EP_TYPE_BULK                       0x02\r
 102 \r
 103                 /** Mask for an INTERRUPT type endpoint or pipe.\r
 104                  *\r
 105                  *  @note See @ref Group_EndpointManagement and @ref Group_PipeManagement for endpoint/pipe functions.\r
 106                  */\r
 107                 #define EP_TYPE_INTERRUPT                  0x03\r
 108                 //@}\r
 109 \r
 110                 #include "Events.h"\r
 111                 #include "USBTask.h"\r
 112                 #include "USBInterrupt.h"\r
 113                 \r
 114                 #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__)\r
 115                         #include "Host.h"\r
 116                         #include "OTG.h"\r
 117                         #include "Pipe.h"\r
 118                         #include "HostStandardReq.h"\r
 119                         #include "PipeStream.h"\r
 120                 #endif\r
 121 \r
 122                 #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__)\r
 123                         #include "Device.h"\r
 124                         #include "Endpoint.h"\r
 125                         #include "DeviceStandardReq.h"\r
 126                         #include "EndpointStream.h"\r
 127                 #endif\r
 128                 \r
 129                 /* Public Interface - May be used in end-application: */\r
 130                 /* Macros: */\r
 131                 /** @name USB Controller Option Masks */\r
 132                 //@{\r
 133                 /** Regulator disable option mask for @ref USB_Init(). This indicates that the internal 3.3V USB data pad\r
 134                  *  regulator should be disabled and the LPC's VCC level used for the data pads.\r
 135                  *\r
 136                  *  @note See USB LPC data sheet for more information on the internal pad regulator.\r
 137                  */\r
 138                                         #define USB_OPT_REG_DISABLED               (1 << 1)\r
 139 \r
 140                 /** Regulator enable option mask for @ref USB_Init(). This indicates that the internal 3.3V USB data pad\r
 141                  *  regulator should be enabled to regulate the data pin voltages from the VBUS level down to a level within\r
 142                  *  the range allowable by the USB standard.\r
 143                  *\r
 144                  *  @note See USB LPC data sheet for more information on the internal pad regulator.\r
 145                  */\r
 146                                         #define USB_OPT_REG_ENABLED                (0 << 1)\r
 147 \r
 148                 /** Manual PLL control option mask for @ref USB_Init(). This indicates to the library that the user application\r
 149                  *  will take full responsibility for controlling the LPC's PLL (used to generate the high frequency clock\r
 150                  *  that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations.\r
 151                  */\r
 152                                         #define USB_OPT_MANUAL_PLL                 (1 << 2)\r
 153 \r
 154                 /** Automatic PLL control option mask for @ref USB_Init(). This indicates to the library that the library should\r
 155                  *  take full responsibility for controlling the LPC's PLL (used to generate the high frequency clock\r
 156                  *  that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations.\r
 157                  */\r
 158                                         #define USB_OPT_AUTO_PLL                   (0 << 2)\r
 159                                         //@}\r
 160                                         \r
 161                                         #if !defined(USB_STREAM_TIMEOUT_MS) || defined(__DOXYGEN__)\r
 162                 /** Constant for the maximum software timeout period of the USB data stream transfer functions\r
 163                  *  (both control and standard) when in either device or host mode. If the next packet of a stream\r
 164                  *  is not received or acknowledged within this time period, the stream function will fail.\r
 165                  *\r
 166                  *  This value may be overridden in the user project makefile as the value of the\r
 167                  *  @ref USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch.\r
 168                  */\r
 169                                                 #define USB_STREAM_TIMEOUT_MS       100\r
 170                                         #endif\r
 171 \r
 172                 /* Inline Functions: */\r
 173                                         #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) || \\r
 174                         defined(__DOXYGEN__)\r
 175                 /**\r
 176                  * @brief  Determines if the VBUS line is currently high (i.e. the USB host is supplying power).\r
 177                  *\r
 178                  *  @note This function is not available on some AVR models which do not support hardware VBUS monitoring.\r
 179                  *\r
 180                  *  @return Boolean \c true if the VBUS line is currently detecting power from a host, \c false otherwise.\r
 181                  */\r
 182                 PRAGMA_ALWAYS_INLINE\r
 183                 static inline bool USB_VBUS_GetStatus(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 184 \r
 185                 static inline bool USB_VBUS_GetStatus(void)\r
 186                 {\r
 187                         return (USBSTA & (1 << VBUS)) ? true : false;\r
 188                 }\r
 189 \r
 190                                         #endif\r
 191 \r
 192                 /** Detaches the device from the USB bus. This has the effect of removing the device from any\r
 193                  *  attached host, ceasing USB communications. If no host is present, this prevents any host from\r
 194                  *  enumerating the device once attached until @ref USB_Attach() is called.\r
 195                  */\r
 196                 PRAGMA_ALWAYS_INLINE\r
 197                 static inline void USB_Detach(void) ATTR_ALWAYS_INLINE;\r
 198 \r
 199                 static inline void USB_Detach(void)\r
 200                 {}\r
 201 \r
 202                 /** Attaches the device to the USB bus. This announces the device's presence to any attached\r
 203                  *  USB host, starting the enumeration process. If no host is present, attaching the device\r
 204                  *  will allow for enumeration once a host is connected to the device.\r
 205                  *\r
 206                  *  This is inexplicably also required for proper operation while in host mode, to enable the\r
 207                  *  attachment of a device to the host. This is despite the bit being located in the device-mode\r
 208                  *  register and despite the datasheet making no mention of its requirement in host mode.\r
 209                  */\r
 210                 PRAGMA_ALWAYS_INLINE\r
 211                 static inline void USB_Attach(void) ATTR_ALWAYS_INLINE;\r
 212 \r
 213                 static inline void USB_Attach(void)\r
 214                 {}\r
 215 \r
 216                 /* Function Prototypes: */\r
 217                 /** Main function to initialize and start the USB interface. Once active, the USB interface will\r
 218                  *  allow for device connection to a host when in device mode, or for device enumeration while in\r
 219                  *  host mode.\r
 220                  *\r
 221                  *  As the USB library relies on interrupts for the device and host mode enumeration processes,\r
 222                  *  the user must enable global interrupts before or shortly after this function is called. In\r
 223                  *  device mode, interrupts must be enabled within 500ms of this function being called to ensure\r
 224                  *  that the host does not time out whilst enumerating the device. In host mode, interrupts may be\r
 225                  *  enabled at the application's leisure however enumeration will not begin of an attached device\r
 226                  *  until after this has occurred.\r
 227                  *\r
 228                  *  Calling this function when the USB interface is already initialized will cause a complete USB\r
 229                  *  interface reset and re-enumeration.\r
 230                  *\r
 231                  *  \see @ref Group_Device for the \c USB_DEVICE_OPT_* masks.\r
 232                  */\r
 233                 void USB_Init(uint8_t corenum, uint8_t mode);\r
 234 \r
 235                 /** Shuts down the USB interface. This turns off the USB interface after deallocating all USB FIFO\r
 236                  *  memory, endpoints and pipes. When turned off, no USB functionality can be used until the interface\r
 237                  *  is restarted with the @ref USB_Init() function.\r
 238                  */\r
 239                 void USB_Disable(uint8_t corenum, uint8_t mode);\r
 240 \r
 241                 /** Resets the interface, when already initialized. This will re-enumerate the device if already connected\r
 242                  *  to a host, or re-enumerate an already attached device when in host mode.\r
 243                  */\r
 244                 void USB_ResetInterface(uint8_t corenum, uint8_t mode);\r
 245 \r
 246                 /* Global Variables: */\r
 247                 extern volatile uint8_t USB_CurrentMode[];\r
 248                 //                      #if (!defined(USB_HOST_ONLY) && !defined(USB_DEVICE_ONLY)) || defined(__DOXYGEN__)\r
 249                 /** Indicates the mode that the USB interface is currently initialized to, a value from the\r
 250                  *  @ref USB_Modes_t enum.\r
 251                  *\r
 252                  *  @note This variable should be treated as read-only in the user application, and never manually\r
 253                  *        changed in value.\r
 254                  *\r
 255                  *  @note When the controller is initialized into UID auto-detection mode, this variable will hold the\r
 256                  *        currently selected USB mode (i.e. @ref USB_MODE_Device or @ref USB_MODE_Host). If the controller\r
 257                  *        is fixed into a specific mode (either through the \c USB_DEVICE_ONLY or \c USB_HOST_ONLY compile time\r
 258                  *        options, or a limitation of the USB controller in the chosen device model) this will evaluate to\r
 259                  *        a constant of the appropriate value and will never evaluate to @ref USB_MODE_None even when the\r
 260                  *        USB interface is not initialized.\r
 261                  */\r
 262                 // extern volatile uint8_t USB_CurrentMode[];\r
 263                 //                      #elif defined(USB_HOST_ONLY)\r
 264                 //                              #define USB_CurrentMode[0] USB_MODE_Host\r
 265                 //                      #elif defined(USB_DEVICE_ONLY)\r
 266                 //                              #define USB_CurrentMode[0] USB_MODE_Device\r
 267                 //                      #endif\r
 268 \r
 269                                         #if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__)\r
 270                 /** Indicates the current USB options that the USB interface was initialized with when @ref USB_Init()\r
 271                  *  was called. This value will be one of the \c USB_MODE_* masks defined elsewhere in this module.\r
 272                  *\r
 273                  *  @note This variable should be treated as read-only in the user application, and never manually\r
 274                  *        changed in value.\r
 275                  */\r
 276                 extern volatile uint8_t USB_Options;\r
 277                                         #elif defined(USE_STATIC_OPTIONS)\r
 278                                                 #define USB_Options USE_STATIC_OPTIONS\r
 279                                         #endif\r
 280 \r
 281                 /* Enums: */\r
 282                 /** Enum for the possible USB controller modes, for initialization via @ref USB_Init() and indication back to the\r
 283                  *  user application via @ref USB_CurrentMode.\r
 284                  */\r
 285                 enum USB_Modes_t {\r
 286                         USB_MODE_None   = 0,                    /**< Indicates that the controller is currently not initialized in any specific USB mode. */\r
 287                         USB_MODE_Device = 1,                    /**< Indicates that the controller is currently initialized in USB Device mode. */\r
 288                         USB_MODE_Host   = 2,                    /**< Indicates that the controller is currently initialized in USB Host mode. */\r
 289                         USB_MODE_UID    = 3,                    /**< Indicates that the controller should determine the USB mode from the UID pin of the\r
 290                                                                                          *   USB connector.\r
 291                                                                                          */\r
 292                 };\r
 293 \r
 294                 /* Private Interface - For use in library only: */\r
 295                         #if !defined(__DOXYGEN__)\r
 296                 /* Function Prototypes: */\r
 297                                         #if defined(__INCLUDE_FROM_USB_CONTROLLER_C)\r
 298                                                 #if defined(USB_CAN_BE_DEVICE)\r
 299                 static void USB_Init_Device(uint8_t corenum);\r
 300 \r
 301                                                 #endif\r
 302 \r
 303                                                 #if defined(USB_CAN_BE_HOST)\r
 304                 static void USB_Init_Host(uint8_t corenum);\r
 305 \r
 306                                                 #endif\r
 307                                         #endif\r
 308 \r
 309                 /* Inline Functions: */\r
 310                 PRAGMA_ALWAYS_INLINE\r
 311                 static inline void USB_PLL_On(void) ATTR_ALWAYS_INLINE;\r
 312 \r
 313                 static inline void USB_PLL_On(void)\r
 314                 {}\r
 315 \r
 316                 PRAGMA_ALWAYS_INLINE\r
 317                 static inline void USB_PLL_Off(void) ATTR_ALWAYS_INLINE;\r
 318 \r
 319                 static inline void USB_PLL_Off(void)\r
 320                 {}\r
 321 \r
 322                 PRAGMA_ALWAYS_INLINE\r
 323                 static inline bool USB_PLL_IsReady(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 324 \r
 325                 static inline bool USB_PLL_IsReady(void)\r
 326                 {\r
 327                         return true;                    // implement later if needed\r
 328                 }\r
 329 \r
 330                 PRAGMA_ALWAYS_INLINE\r
 331                 static inline void USB_REG_On(void) ATTR_ALWAYS_INLINE;\r
 332 \r
 333                 static inline void USB_REG_On(void)\r
 334                 {}\r
 335 \r
 336                 PRAGMA_ALWAYS_INLINE\r
 337                 static inline void USB_REG_Off(void) ATTR_ALWAYS_INLINE;\r
 338 \r
 339                 static inline void USB_REG_Off(void)\r
 340                 {}\r
 341 \r
 342                 PRAGMA_ALWAYS_INLINE\r
 343                 static inline void USB_OTGPAD_On(void) ATTR_ALWAYS_INLINE;\r
 344 \r
 345                 static inline void USB_OTGPAD_On(void)\r
 346                 {}\r
 347 \r
 348                 PRAGMA_ALWAYS_INLINE\r
 349                 static inline void USB_OTGPAD_Off(void) ATTR_ALWAYS_INLINE;\r
 350 \r
 351                 static inline void USB_OTGPAD_Off(void)\r
 352                 {}\r
 353 \r
 354                 PRAGMA_ALWAYS_INLINE\r
 355                 static inline void USB_CLK_Freeze(void) ATTR_ALWAYS_INLINE;\r
 356 \r
 357                 static inline void USB_CLK_Freeze(void)\r
 358                 {}\r
 359 \r
 360                 PRAGMA_ALWAYS_INLINE\r
 361                 static inline void USB_CLK_Unfreeze(void) ATTR_ALWAYS_INLINE;\r
 362 \r
 363                 static inline void USB_CLK_Unfreeze(void)\r
 364                 {}\r
 365 \r
 366                 PRAGMA_ALWAYS_INLINE\r
 367                 static inline void USB_Controller_Enable(void) ATTR_ALWAYS_INLINE;\r
 368 \r
 369                 static inline void USB_Controller_Enable(void)\r
 370                 {}\r
 371 \r
 372                 PRAGMA_ALWAYS_INLINE\r
 373                 static inline void USB_Controller_Disable(void) ATTR_ALWAYS_INLINE;\r
 374 \r
 375                 static inline void USB_Controller_Disable(void)\r
 376                 {}\r
 377 \r
 378                 PRAGMA_ALWAYS_INLINE\r
 379                 static inline void USB_Controller_Reset(void) ATTR_ALWAYS_INLINE;\r
 380 \r
 381                 static inline void USB_Controller_Reset(void)\r
 382                 {}\r
 383 \r
 384                                         #if defined(USB_CAN_BE_BOTH)\r
 385                 PRAGMA_ALWAYS_INLINE\r
 386                 static inline uint8_t USB_GetUSBModeFromUID(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
 387 \r
 388                 static inline uint8_t USB_GetUSBModeFromUID(void)\r
 389                 {\r
 390                         // if (USBSTA & (1 << ID))\r
 391                         //  return USB_MODE_Device;\r
 392                         // else\r
 393                         //  return USB_MODE_Host;\r
 394                         return 0;\r
 395                 }\r
 396 \r
 397                                         #endif\r
 398 \r
 399                         #endif\r
 400 \r
 401 \r
 402         /* Disable C linkage for C++ Compilers: */\r
 403                 #if defined(__cplusplus)\r
 404                         }\r
 405                 #endif\r
 406 \r
 407 #endif\r
 408 \r
 409 /** @} */\r
 410 \r