USBController.h 18.4 KB
 Dean Camera committed May 08, 2010 1 2 3 /* LUFA Library Copyright (C) Dean Camera, 2010.  4   Dean Camera committed May 08, 2010 5 6 7 8 9 10 11  dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)  12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 15  all copies and that both that the copyright notice and this  16 17 18  permission notice and warranty disclaimer appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the  Dean Camera committed May 08, 2010 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33  software without specific, written prior permission. The author disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. */ /** \file * \brief USB low level USB controller definitions. *  Dean Camera committed Jun 16, 2010 34  * This file contains structures, function prototypes and macros related to the low level configuration of the  Dean Camera committed May 08, 2010 35 36 37 38 39  * USB controller, to start, stop and reset the USB library core. * * \note This file should not be included directly. It is automatically included as needed by the USB driver * dispatch header located in LUFA/Drivers/USB/USB.h. */  40   Dean Camera committed May 08, 2010 41 42 43 44 45 46 47 48 /** \ingroup Group_USB * @defgroup Group_USBManagement USB Interface Management * * Functions, macros, variables, enums and types related to the setup and management of the USB interface. * * @{ */  Dean Camera committed Jul 21, 2010 49 50 #ifndef __USBCONTROLLER_H__ #define __USBCONTROLLER_H__  Dean Camera committed May 08, 2010 51 52 53 54 55  /* Includes: */ #include #include #include  56   Dean Camera committed May 08, 2010 57 58 59 60 61 62 63  #include "../HighLevel/USBMode.h" #include "../../../Common/Common.h" #include "../HighLevel/USBMode.h" #include "../HighLevel/Events.h" #include "../HighLevel/USBTask.h" #include "USBInterrupt.h"  64   Dean Camera committed May 08, 2010 65 66 67  #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) #include "Host.h" #include "OTG.h"  Dean Camera committed Aug 22, 2010 68  #include "Pipe.h"  Dean Camera committed Jul 21, 2010 69  #include "../HighLevel/HostStandardReq.h"  Dean Camera committed Aug 22, 2010 70  #include "../HighLevel/PipeStream.h"  Dean Camera committed May 08, 2010 71  #endif  72   Dean Camera committed May 08, 2010 73 74 75  #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) #include "Device.h" #include "Endpoint.h"  Dean Camera committed Jul 21, 2010 76  #include "../HighLevel/DeviceStandardReq.h"  Dean Camera committed Aug 22, 2010 77  #include "../HighLevel/EndpointStream.h"  Dean Camera committed May 08, 2010 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92  #endif /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks and Defines: */ #if !defined(__INCLUDE_FROM_USB_DRIVER) #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. #endif #if !defined(F_CLOCK) #error F_CLOCK is not defined. You must define F_CLOCK to the frequency of the unprescaled input clock in your project makefile. #endif  93   Dean Camera committed May 08, 2010 94 95 96  #if (F_CLOCK == 8000000) #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \ defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \  Dean Camera committed Jul 21, 2010 97  defined(__AVR_ATmega32U2__))  Dean Camera committed May 08, 2010 98 99 100 101 102 103 104 105 106 107 108  #define USB_PLL_PSC 0 #elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__)) #define USB_PLL_PSC 0 #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB1286__) || defined(__AVR_ATmega32U6__)) #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0)) #elif (defined(__AVR_AT90USB647__) || defined(__AVR_AT90USB1287__)) #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0)) #endif #elif (F_CLOCK == 16000000) #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \ defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \  Dean Camera committed Jul 21, 2010 109  defined(__AVR_ATmega32U2__))  Dean Camera committed May 08, 2010 110 111 112 113 114 115 116 117 118  #define USB_PLL_PSC (1 << PLLP0) #elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__)) #define USB_PLL_PSC (1 << PINDIV) #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || defined(__AVR_ATmega32U6__)) #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP1)) #elif (defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__)) #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP0)) #endif #endif  119   Dean Camera committed May 08, 2010 120  #if !defined(USB_PLL_PSC)  Dean Camera committed Oct 24, 2010 121  #error No PLL prescale value available for chosen F_CLOCK value and AVR model.  Dean Camera committed May 08, 2010 122  #endif  123   Dean Camera committed May 08, 2010 124  /* Public Interface - May be used in end-application: */  125  /* Macros: */  Dean Camera committed May 08, 2010 126 127 128 129 130 131 132 133 134 135 136 137 138  /** Regulator disable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad * regulator should be enabled to regulate the data pin voltages to within the USB standard. * * \note See USB AVR data sheet for more information on the internal pad regulator. */ #define USB_OPT_REG_DISABLED (1 << 1) /** Regulator enable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad * regulator should be disabled and the AVR's VCC level used for the data pads. * * \note See USB AVR data sheet for more information on the internal pad regulator. */ #define USB_OPT_REG_ENABLED (0 << 1)  139   Dean Camera committed May 08, 2010 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175  /** Manual PLL control option mask for \ref USB_Init(). This indicates to the library that the user application * will take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock * that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations. */ #define USB_OPT_MANUAL_PLL (1 << 2) /** Automatic PLL control option mask for \ref USB_Init(). This indicates to the library that the library should * take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock * that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations. */ #define USB_OPT_AUTO_PLL (0 << 2) /** Mask for a CONTROL type endpoint or pipe. * * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ #define EP_TYPE_CONTROL 0x00 /** Mask for an ISOCHRONOUS type endpoint or pipe. * * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ #define EP_TYPE_ISOCHRONOUS 0x01 /** Mask for a BULK type endpoint or pipe. * * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ #define EP_TYPE_BULK 0x02 /** Mask for an INTERRUPT type endpoint or pipe. * * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ #define EP_TYPE_INTERRUPT 0x03  Dean Camera committed Jul 22, 2010 176 177 178 179 180  #if !defined(USB_STREAM_TIMEOUT_MS) || defined(__DOXYGEN__) /** Constant for the maximum software timeout period of the USB data stream transfer functions * (both control and standard) when in either device or host mode. If the next packet of a stream * is not received or acknowledged within this time period, the stream function will fail. *  181  * This value may be overridden in the user project makefile as the value of the  Dean Camera committed Jul 22, 2010 182 183 184 185  * \ref USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch. */ #define USB_STREAM_TIMEOUT_MS 100 #endif  186   Dean Camera committed Jul 22, 2010 187  /* Inline Functions: */  Dean Camera committed May 08, 2010 188 189 190 191  #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) || defined(__DOXYGEN__) /** Returns boolean true if the VBUS line is currently high (i.e. the USB host is supplying power), * otherwise returns false. *  Dean Camera committed Jul 22, 2010 192  * \note This function is not available on some AVR models which do not support hardware VBUS monitoring.  Dean Camera committed May 08, 2010 193  */  Dean Camera committed Jul 22, 2010 194 195 196 197 198  static inline bool USB_VBUS_GetStatus(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline bool USB_VBUS_GetStatus(void) { return ((USBSTA & (1 << VBUS)) ? true : false); }  Dean Camera committed May 08, 2010 199 200 201 202 203 204  #endif /** Detaches the device from the USB bus. This has the effect of removing the device from any * attached host, ceasing USB communications. If no host is present, this prevents any host from * enumerating the device once attached until \ref USB_Attach() is called. */  Dean Camera committed Jul 22, 2010 205 206 207 208 209  static inline void USB_Detach(void) ATTR_ALWAYS_INLINE; static inline void USB_Detach(void) { UDCON |= (1 << DETACH); }  Dean Camera committed May 08, 2010 210 211 212 213 214 215 216 217 218  /** Attaches the device to the USB bus. This announces the device's presence to any attached * USB host, starting the enumeration process. If no host is present, attaching the device * will allow for enumeration once a host is connected to the device. * * This is inexplicably also required for proper operation while in host mode, to enable the * attachment of a device to the host. This is despite the bit being located in the device-mode * register and despite the datasheet making no mention of its requirement in host mode. */  Dean Camera committed Jul 22, 2010 219 220 221 222 223  static inline void USB_Attach(void) ATTR_ALWAYS_INLINE; static inline void USB_Attach(void) { UDCON &= ~(1 << DETACH); }  Dean Camera committed May 08, 2010 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239  /* Function Prototypes: */ /** Main function to initialize and start the USB interface. Once active, the USB interface will * allow for device connection to a host when in device mode, or for device enumeration while in * host mode. * * As the USB library relies on interrupts for the device and host mode enumeration processes, * the user must enable global interrupts before or shortly after this function is called. In * device mode, interrupts must be enabled within 500ms of this function being called to ensure * that the host does not time out whilst enumerating the device. In host mode, interrupts may be * enabled at the application's leisure however enumeration will not begin of an attached device * until after this has occurred. * * Calling this function when the USB interface is already initialized will cause a complete USB * interface reset and re-enumeration. *  Dean Camera committed Oct 12, 2010 240 241  * \param[in] Mode This is a mask indicating what mode the USB interface is to be initialized to, a value * from the \ref USB_Modes_t enum.  Dean Camera committed May 08, 2010 242 243  * * \param[in] Options Mask indicating the options which should be used when initializing the USB  Dean Camera committed Jul 30, 2010 244  * interface to control the USB interface's behaviour. This should be comprised of  Dean Camera committed May 08, 2010 245 246 247 248  * a USB_OPT_REG_* mask to control the regulator, a USB_OPT_*_PLL mask to control the * PLL, and a USB_DEVICE_OPT_* mask (when the device mode is enabled) to set the device * mode speed. *  249  * \note To reduce the FLASH requirements of the library if only device or host mode is required,  Dean Camera committed May 08, 2010 250  * the mode can be statically set in the project makefile by defining the token USB_DEVICE_ONLY  251  * (for device mode) or USB_HOST_ONLY (for host mode), passing the token to the compiler  Dean Camera committed May 08, 2010 252 253 254 255 256  * via the -D switch. If the mode is statically set, this parameter does not exist in the * function prototype. * \n\n * * \note To reduce the FLASH requirements of the library if only fixed settings are are required,  257  * the options may be set statically in the same manner as the mode (see the Mode parameter of  Dean Camera committed May 08, 2010 258 259 260 261  * this function). To statically set the USB options, pass in the USE_STATIC_OPTIONS token, * defined to the appropriate options masks. When the options are statically set, this * parameter does not exist in the function prototype. * \n\n  262 263  * * \note The mode parameter does not exist on devices where only one mode is possible, such as USB  Dean Camera committed May 08, 2010 264 265 266 267 268 269 270  * AVR models which only implement the USB device mode in hardware. * * \see Device.h for the USB_DEVICE_OPT_* masks. */ void USB_Init( #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__) const uint8_t Mode  Dean Camera committed Jul 21, 2010 271  #endif  Dean Camera committed May 08, 2010 272 273 274  #if (defined(USB_CAN_BE_BOTH) && !defined(USE_STATIC_OPTIONS)) || defined(__DOXYGEN__) ,  Dean Camera committed Jul 21, 2010 275 276  #elif (!defined(USB_CAN_BE_BOTH) && defined(USE_STATIC_OPTIONS)) void  Dean Camera committed May 08, 2010 277  #endif  Dean Camera committed Jul 21, 2010 278   Dean Camera committed May 08, 2010 279 280 281 282  #if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__) const uint8_t Options #endif );  283   Dean Camera committed May 08, 2010 284 285 286 287 288 289 290 291 292 293 294 295 296  /** Shuts down the USB interface. This turns off the USB interface after deallocating all USB FIFO * memory, endpoints and pipes. When turned off, no USB functionality can be used until the interface * is restarted with the \ref USB_Init() function. */ void USB_ShutDown(void); /** Resets the interface, when already initialized. This will re-enumerate the device if already connected * to a host, or re-enumerate an already attached device when in host mode. */ void USB_ResetInterface(void); /* Global Variables: */ #if (!defined(USB_HOST_ONLY) && !defined(USB_DEVICE_ONLY)) || defined(__DOXYGEN__)  Dean Camera committed Oct 12, 2010 297 298  /** Indicates the mode that the USB interface is currently initialized to, a value from the * \ref USB_Modes_t enum.  Dean Camera committed May 08, 2010 299 300 301  * * \note This variable should be treated as read-only in the user application, and never manually * changed in value.  Dean Camera committed Oct 12, 2010 302 303 304 305 306 307 308 309  * \n\n * * \note When the controller is initialized into UID autodetection mode, this variable will hold the * currently selected USB mode (i.e. \ref USB_MODE_Device or \ref USB_MODE_Host). If the controller * is fixed into a specific mode (either through the USB_DEVICE_ONLY or USB_HOST_ONLY compile time * options, or a limitation of the USB controller in the chosen device model) this will evaluate to * a constant of the appropriate value and will never evaluate to \ref USB_MODE_None even when the * USB interface is not initialized.  Dean Camera committed May 08, 2010 310 311 312  */ extern volatile uint8_t USB_CurrentMode; #elif defined(USB_HOST_ONLY)  Dean Camera committed Oct 12, 2010 313  #define USB_CurrentMode USB_MODE_Host  Dean Camera committed May 08, 2010 314  #elif defined(USB_DEVICE_ONLY)  Dean Camera committed Oct 12, 2010 315  #define USB_CurrentMode USB_MODE_Device  Dean Camera committed May 08, 2010 316  #endif  317   Dean Camera committed May 08, 2010 318 319 320 321 322 323 324 325 326 327 328 329  #if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__) /** Indicates the current USB options that the USB interface was initialized with when \ref USB_Init() * was called. This value will be one of the USB_MODE_* masks defined elsewhere in this module. * * \note This variable should be treated as read-only in the user application, and never manually * changed in value. */ extern volatile uint8_t USB_Options; #elif defined(USE_STATIC_OPTIONS) #define USB_Options USE_STATIC_OPTIONS #endif  Dean Camera committed Oct 12, 2010 330 331 332 333 334 335 336 337 338 339 340 341 342 343  /* Enums: */ /** Enum for the possible USB controller modes, for initialization via \ref USB_Init() and indication back to the * user application via \ref USB_CurrentMode. */ enum USB_Modes_t { USB_MODE_None = 0, /**< Indicates that the controller is currently not initialized in any specific USB mode. */ USB_MODE_Device = 1, /**< Indicates that the controller is currently initialized in USB Device mode. */ USB_MODE_Host = 2, /**< Indicates that the controller is currently initialized in USB Host mode. */ USB_MODE_UID = 3, /**< Indicates that the controller should determine the USB mode from the UID pin of the * USB connector. */ };  Dean Camera committed May 08, 2010 344 345  /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__)  346 347 348 349 350  /* Function Prototypes: */ #if defined(__INCLUDE_FROM_USB_CONTROLLER_C) #if defined(USB_CAN_BE_DEVICE) static void USB_Init_Device(void); #endif  351   352 353 354 355  #if defined(USB_CAN_BE_HOST) static void USB_Init_Host(void); #endif #endif  356   Dean Camera committed Jul 22, 2010 357 358 359 360 361 362 363  /* Inline Functions: */ static inline void USB_PLL_On(void) ATTR_ALWAYS_INLINE; static inline void USB_PLL_On(void) { PLLCSR = USB_PLL_PSC; PLLCSR |= (1 << PLLE); }  364   Dean Camera committed Jul 22, 2010 365 366 367 368 369  static inline void USB_PLL_Off(void) ATTR_ALWAYS_INLINE; static inline void USB_PLL_Off(void) { PLLCSR = 0; }  370   Dean Camera committed Jul 22, 2010 371 372 373 374 375 376 377 378 379 380 381 382 383  static inline bool USB_PLL_IsReady(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline bool USB_PLL_IsReady(void) { return ((PLLCSR & (1 << PLOCK)) ? true : false); } static inline void USB_REG_On(void) ATTR_ALWAYS_INLINE; static inline void USB_REG_On(void) { #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) UHWCON |= (1 << UVREGE); #else REGCR &= ~(1 << REGDIS);  384  #endif  Dean Camera committed Jul 22, 2010 385  }  Dean Camera committed May 08, 2010 386   Dean Camera committed Jul 22, 2010 387 388 389  static inline void USB_REG_Off(void) ATTR_ALWAYS_INLINE; static inline void USB_REG_Off(void) {  Dean Camera committed May 08, 2010 390  #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)  Dean Camera committed Jul 22, 2010 391  UHWCON &= ~(1 << UVREGE);  Dean Camera committed May 08, 2010 392  #else  Dean Camera committed Jul 22, 2010 393  REGCR |= (1 << REGDIS);  394  #endif  Dean Camera committed Jul 22, 2010 395  }  396   Dean Camera committed Jul 22, 2010 397 398 399 400 401 402 403 404 405 406 407 408  #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) static inline void USB_OTGPAD_On(void) ATTR_ALWAYS_INLINE; static inline void USB_OTGPAD_On(void) { USBCON |= (1 << OTGPADE); } static inline void USB_OTGPAD_Off(void) ATTR_ALWAYS_INLINE; static inline void USB_OTGPAD_Off(void) { USBCON &= ~(1 << OTGPADE); }  Dean Camera committed May 08, 2010 409  #endif  Dean Camera committed Jul 22, 2010 410 411 412 413 414 415  static inline void USB_CLK_Freeze(void) ATTR_ALWAYS_INLINE; static inline void USB_CLK_Freeze(void) { USBCON |= (1 << FRZCLK); }  416   Dean Camera committed Jul 22, 2010 417 418 419 420 421  static inline void USB_CLK_Unfreeze(void) ATTR_ALWAYS_INLINE; static inline void USB_CLK_Unfreeze(void) { USBCON &= ~(1 << FRZCLK); }  422   Dean Camera committed Jul 22, 2010 423 424 425 426 427  static inline void USB_Controller_Enable(void) ATTR_ALWAYS_INLINE; static inline void USB_Controller_Enable(void) { USBCON |= (1 << USBE); }  Dean Camera committed May 08, 2010 428   Dean Camera committed Jul 22, 2010 429 430 431 432 433  static inline void USB_Controller_Disable(void) ATTR_ALWAYS_INLINE; static inline void USB_Controller_Disable(void) { USBCON &= ~(1 << USBE); }  Dean Camera committed May 08, 2010 434   Dean Camera committed Jul 22, 2010 435 436 437 438  static inline void USB_Controller_Reset(void) ATTR_ALWAYS_INLINE; static inline void USB_Controller_Reset(void) { const uint8_t Temp = USBCON;  439   Dean Camera committed Jul 22, 2010 440 441 442  USBCON = (Temp & ~(1 << USBE)); USBCON = (Temp | (1 << USBE)); }  443   Dean Camera committed May 08, 2010 444 445 446 447 448  #if defined(USB_CAN_BE_BOTH) static inline uint8_t USB_GetUSBModeFromUID(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint8_t USB_GetUSBModeFromUID(void) { if (USBSTA & (1 << ID))  Dean Camera committed Oct 12, 2010 449  return USB_MODE_Device;  Dean Camera committed May 08, 2010 450  else  Dean Camera committed Oct 12, 2010 451  return USB_MODE_Host;  Dean Camera committed May 08, 2010 452 453  } #endif  454   Dean Camera committed May 08, 2010 455  #endif  456   Dean Camera committed May 08, 2010 457 458 459 460  /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif  461   Dean Camera committed May 08, 2010 462 463 464 #endif /** @} */  465