/*\r
LUFA Library\r
- Copyright (C) Dean Camera, 2009.\r
+ Copyright (C) Dean Camera, 2010.\r
\r
dean [at] fourwalledcubicle [dot] com\r
www.fourwalledcubicle.com\r
*/\r
\r
/*\r
- Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
+ Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
\r
- Permission to use, copy, modify, and distribute this software\r
- and its documentation for any purpose and without fee is hereby\r
- granted, provided that the above copyright notice appear in all\r
- copies and that both that the copyright notice and this\r
- permission notice and warranty disclaimer appear in supporting\r
- documentation, and that the name of the author not be used in\r
- advertising or publicity pertaining to distribution of the\r
+ Permission to use, copy, modify, distribute, and sell this \r
+ software and its documentation for any purpose is hereby granted\r
+ without fee, provided that the above copyright notice appear in \r
+ all copies and that both that the copyright notice and this\r
+ permission notice and warranty disclaimer appear in supporting \r
+ documentation, and that the name of the author not be used in \r
+ advertising or publicity pertaining to distribution of the \r
software without specific, written prior permission.\r
\r
The author disclaim all warranties with regard to this\r
this software.\r
*/\r
\r
-/** \file\r
+/** \ingroup Group_USB\r
+ * @defgroup Group_USBManagement USB Interface Management\r
*\r
- * Main low level USB driver. This module manages the low level initialization and shut down of the USB AVR's\r
- * USB interface in either device or (if supported) host mode.\r
+ * Functions, macros, variables, enums and types related to the setup and management of the USB interface.\r
+ *\r
+ * @{\r
*/\r
\r
#ifndef __USBLOWLEVEL_H__\r
#include <avr/interrupt.h>\r
#include <stdbool.h>\r
\r
- #include "USBMode.h"\r
+ #include "../HighLevel/USBMode.h"\r
+\r
#include "../../../Common/Common.h"\r
+ #include "../HighLevel/USBMode.h"\r
#include "../HighLevel/Events.h"\r
#include "../HighLevel/USBTask.h"\r
#include "../HighLevel/USBInterrupt.h"\r
#endif\r
\r
/* Preprocessor Checks and Defines: */\r
- #if (F_CPU == 8000000)\r
- #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__))\r
+ #if !defined(F_CLOCK)\r
+ #error F_CLOCK is not defined. You must define F_CLOCK to the frequency of the unprescaled input clock in your project makefile.\r
+ #endif\r
+ \r
+ #if (F_CLOCK == 8000000)\r
+ #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \\r
+ defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \\r
+ defined(__AVR_ATmega32U2__))\r
#define USB_PLL_PSC 0\r
- #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || \\r
- defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__) || \\r
- defined(__AVR_ATmega32U6__))\r
- #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0))\r
#elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__))\r
#define USB_PLL_PSC 0\r
+ #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB1286__) || defined(__AVR_ATmega32U6__))\r
+ #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0))\r
+ #elif (defined(__AVR_AT90USB647__) || defined(__AVR_AT90USB1287__))\r
+ #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0))\r
#endif\r
- #elif (F_CPU == 16000000)\r
- #if (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || defined(__AVR_ATmega32U6__))\r
- #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP1))\r
- #elif (defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__))\r
- #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP0))\r
- #elif (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__))\r
+ #elif (F_CLOCK == 16000000)\r
+ #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \\r
+ defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \\r
+ defined(__AVR_ATmega32U2__))\r
#define USB_PLL_PSC (1 << PLLP0)\r
#elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__))\r
#define USB_PLL_PSC (1 << PINDIV)\r
+ #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || defined(__AVR_ATmega32U6__))\r
+ #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP1))\r
+ #elif (defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__))\r
+ #define USB_PLL_PSC ((1 << PLLP2) | (1 << PLLP0))\r
#endif\r
#endif\r
\r
\r
/* Public Interface - May be used in end-application: */\r
/* Macros: */\r
- /** Mode mask for the USB_CurrentMode global. This indicates that the USB interface is currently not\r
+ /** Mode mask for the \ref USB_CurrentMode global. This indicates that the USB interface is currently not\r
* initialized into any mode.\r
*/\r
#define USB_MODE_NONE 0\r
\r
- /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the\r
+ /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the\r
* USB interface is or should be initialized in the USB device mode.\r
*/\r
#define USB_MODE_DEVICE 1\r
-\r
- /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the\r
+ \r
+ /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the\r
* USB interface is or should be initialized in the USB host mode.\r
- *\r
- * \note Not all USB AVRs support host mode.\r
*/\r
#define USB_MODE_HOST 2\r
-\r
- /** Mode mask for the the USB_Init() function. This indicates that the USB interface should be\r
- * initialized into whatever mode the UID pin of the USB AVR indicates, and that the device\r
- * should swap over its mode when the level of the UID pin changes during operation.\r
- *\r
- * \note Not all USB AVRs support host mode, and thus UID mode.\r
- */\r
- #define USB_MODE_UID 3\r
\r
- /** Regulator disable option mask for USB_Init(). This indicates that the internal 3.3V USB data pad\r
+ #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__)\r
+ /** Mode mask for the the \ref USB_Init() function. This indicates that the USB interface should be\r
+ * initialized into whatever mode the UID pin of the USB AVR indicates, and that the device\r
+ * should swap over its mode when the level of the UID pin changes during operation.\r
+ *\r
+ * \note This token is not available on AVR models which do not support both host and device modes.\r
+ */\r
+ #define USB_MODE_UID 3\r
+ #endif\r
+ \r
+ /** Regulator disable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad\r
* regulator should be enabled to regulate the data pin voltages to within the USB standard.\r
*\r
* \note See USB AVR data sheet for more information on the internal pad regulator.\r
*/\r
#define USB_OPT_REG_DISABLED (1 << 1)\r
\r
- /** Regulator enable option mask for USB_Init(). This indicates that the internal 3.3V USB data pad\r
+ /** Regulator enable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad\r
* regulator should be disabled and the AVR's VCC level used for the data pads.\r
*\r
* \note See USB AVR data sheet for more information on the internal pad regulator.\r
*/\r
#define USB_OPT_REG_ENABLED (0 << 1)\r
\r
- /** Manual PLL control option mask for USB_Init(). This indicates to the library that the user application\r
+ /** Manual PLL control option mask for \ref USB_Init(). This indicates to the library that the user application\r
* will take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock\r
* that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations.\r
*/\r
#define USB_OPT_MANUAL_PLL (1 << 2)\r
\r
- /** Automatic PLL control option mask for USB_Init(). This indicates to the library that the library should\r
+ /** Automatic PLL control option mask for \ref USB_Init(). This indicates to the library that the library should\r
* take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock\r
* that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations.\r
*/\r
\r
/** Mask for a CONTROL type endpoint or pipe.\r
*\r
- * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions.\r
+ * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions.\r
*/\r
- #define EP_TYPE_CONTROL 0b00\r
+ #define EP_TYPE_CONTROL 0x00\r
\r
/** Mask for an ISOCHRONOUS type endpoint or pipe.\r
*\r
- * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions.\r
+ * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions.\r
*/\r
- #define EP_TYPE_ISOCHRONOUS 0b01\r
+ #define EP_TYPE_ISOCHRONOUS 0x01\r
\r
/** Mask for a BULK type endpoint or pipe.\r
*\r
- * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions.\r
+ * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions.\r
*/\r
- #define EP_TYPE_BULK 0b10\r
+ #define EP_TYPE_BULK 0x02\r
\r
/** Mask for an INTERRUPT type endpoint or pipe.\r
*\r
- * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions.\r
- */\r
- #define EP_TYPE_INTERRUPT 0b11\r
-\r
- /** Mask for determining the type of an endpoint or pipe. This should then be compared with the\r
- * EP_TYPE_* macros elsewhere in this module to determine the exact type of the endpoint or pipe.\r
- *\r
- * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions.\r
+ * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions.\r
*/\r
- #define EP_TYPE_MASK 0b11\r
+ #define EP_TYPE_INTERRUPT 0x03\r
\r
- /** Returns boolean true if the VBUS line is currently high (i.e. the USB host is supplying power),\r
- * otherwise returns false.\r
- */\r
- #define USB_VBUS_GetStatus() ((USBSTA & (1 << VBUS)) ? true : false)\r
+ #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) || defined(__DOXYGEN__)\r
+ /** Returns boolean true if the VBUS line is currently high (i.e. the USB host is supplying power),\r
+ * otherwise returns false.\r
+ *\r
+ * \note This token is not available on some AVR models which do not support hardware VBUS monitoring.\r
+ */\r
+ #define USB_VBUS_GetStatus() ((USBSTA & (1 << VBUS)) ? true : false)\r
+ #endif\r
\r
/** Detaches the device from the USB bus. This has the effect of removing the device from any\r
- * host if, ceasing USB communications. If no host is present, this prevents any host from\r
- * enumerating the device once attached until USB_Attach() is called.\r
+ * attached host, ceasing USB communications. If no host is present, this prevents any host from\r
+ * enumerating the device once attached until \ref USB_Attach() is called.\r
*/\r
#define USB_Detach() MACROS{ UDCON |= (1 << DETACH); }MACROE\r
\r
#if !defined(USB_STREAM_TIMEOUT_MS) || defined(__DOXYGEN__)\r
/** Constant for the maximum software timeout period of the USB data stream transfer functions\r
* (both control and standard) when in either device or host mode. If the next packet of a stream\r
- * is not received or acknowedged within this time period, the stream function will fail.\r
+ * is not received or acknowledged within this time period, the stream function will fail.\r
*\r
* This value may be overridden in the user project makefile as the value of the \r
- * USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch.\r
+ * \ref USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch.\r
*/\r
#define USB_STREAM_TIMEOUT_MS 100\r
#endif\r
* Calling this function when the USB interface is already initialized will cause a complete USB\r
* interface reset and re-enumeration.\r
*\r
- * \param Mode This is a mask indicating what mode the USB interface is to be initialized to.\r
- * Valid mode masks are USB_MODE_DEVICE, USB_MODE_HOST or USB_MODE_UID.\r
+ * \param[in] Mode This is a mask indicating what mode the USB interface is to be initialized to.\r
+ * Valid mode masks are \ref USB_MODE_DEVICE, \ref USB_MODE_HOST or \ref USB_MODE_UID.\r
*\r
- * \param Options Mask indicating the options which should be used when initializing the USB\r
- * interface to control the USB interface's behaviour. This should be comprised of\r
- * a USB_OPT_REG_* mask to control the regulator, a USB_OPT_*_PLL mask to control the\r
- * PLL, and a USB_DEVICE_OPT_* mask (when the device mode is enabled) to set the device\r
- * mode speed.\r
+ * \param[in] Options Mask indicating the options which should be used when initializing the USB\r
+ * interface to control the USB interface's behaviour. This should be comprised of\r
+ * a USB_OPT_REG_* mask to control the regulator, a USB_OPT_*_PLL mask to control the\r
+ * PLL, and a USB_DEVICE_OPT_* mask (when the device mode is enabled) to set the device\r
+ * mode speed.\r
*\r
* \note To reduce the FLASH requirements of the library if only device or host mode is required, \r
* this can be statically set via defining the token USB_DEVICE_ONLY for device mode or \r
\r
/** Shuts down the USB interface. This turns off the USB interface after deallocating all USB FIFO\r
* memory, endpoints and pipes. When turned off, no USB functionality can be used until the interface\r
- * is restarted with the USB_Init() function.\r
+ * is restarted with the \ref USB_Init() function.\r
*/\r
void USB_ShutDown(void);\r
\r
\r
/* Enums: */\r
/** Enum for error codes relating to the powering on of the USB interface. These error codes are\r
- * used in the ErrorCode parameter value of the USB_PowerOnFail event.\r
+ * used in the ErrorCode parameter value of the \ref EVENT_USB_InitFailure() event.\r
*/\r
- enum USB_PowerOnErrorCodes_t\r
+ enum USB_InitErrorCodes_t\r
{\r
- POWERON_ERROR_NoUSBModeSpecified = 0, /**< Indicates that USB_Init() was called with an\r
+ USB_INITERROR_NoUSBModeSpecified = 0, /**< Indicates that \ref USB_Init() was called with an\r
* invalid or missing Mode parameter.\r
*/\r
};\r
* changed in value.\r
*/\r
extern volatile uint8_t USB_CurrentMode;\r
+ #elif defined(USB_HOST_ONLY)\r
+ #define USB_CurrentMode USB_MODE_HOST\r
+ #elif defined(USB_DEVICE_ONLY)\r
+ #define USB_CurrentMode USB_MODE_DEVICE\r
#endif\r
\r
#if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__)\r
- extern volatile uint8_t USB_Options;\r
- /** Indicates the current USB options that the USB interface was initialized with when USB_Init()\r
+ /** Indicates the current USB options that the USB interface was initialized with when \ref USB_Init()\r
* was called. This value will be one of the USB_MODE_* masks defined elsewhere in this module.\r
*\r
* \note This variable should be treated as read-only in the user application, and never manually\r
* changed in value.\r
*/\r
+ extern volatile uint8_t USB_Options;\r
+ #elif defined(USE_STATIC_OPTIONS)\r
+ #define USB_Options USE_STATIC_OPTIONS\r
#endif\r
\r
- /* Throwable Events: */\r
- /** This module raises the USB_Disconnect event if the USB interface is reset (such as during a mode\r
- * change while in UID mode) while the USB interface is connected to a device when in host mode, or\r
- * a host while in device mode.\r
- *\r
- * \see Events.h for more information on this event.\r
- */\r
- RAISES_EVENT(USB_Disconnect);\r
- \r
- #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__)\r
- /** This module raises the Power On Failure event when an error occurs while initializing the USB\r
- * interface.\r
- *\r
- * \see Events.h for more information on this event.\r
- */\r
- RAISES_EVENT(USB_PowerOnFail);\r
- #endif\r
- \r
/* Private Interface - For use in library only: */\r
#if !defined(__DOXYGEN__)\r
/* Macros: */\r
#define USB_PLL_Off() MACROS{ PLLCSR = 0; }MACROE\r
#define USB_PLL_IsReady() ((PLLCSR & (1 << PLOCK)) ? true : false)\r
\r
- #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) \r
+ #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR)\r
#define USB_REG_On() MACROS{ UHWCON |= (1 << UVREGE); }MACROE\r
#define USB_REG_Off() MACROS{ UHWCON &= ~(1 << UVREGE); }MACROE\r
#else\r
#define USB_CLK_Freeze() MACROS{ USBCON |= (1 << FRZCLK); }MACROE\r
#define USB_CLK_Unfreeze() MACROS{ USBCON &= ~(1 << FRZCLK); }MACROE\r
\r
- #define USB_Interface_Enable() MACROS{ USBCON |= (1 << USBE); }MACROE\r
- #define USB_Interface_Disable() MACROS{ USBCON &= ~(1 << USBE); }MACROE\r
- #define USB_Interface_Reset() MACROS{ uint8_t Temp = USBCON; USBCON = (Temp & ~(1 << USBE)); \\r
+ #define USB_Controller_Enable() MACROS{ USBCON |= (1 << USBE); }MACROE\r
+ #define USB_Controller_Disable() MACROS{ USBCON &= ~(1 << USBE); }MACROE\r
+ #define USB_Controller_Reset() MACROS{ const uint8_t Temp = USBCON; USBCON = (Temp & ~(1 << USBE)); \\r
USBCON = (Temp | (1 << USBE)); }MACROE\r
\r
- /* Inline Functions: */ \r
- static inline uint8_t USB_GetUSBModeFromUID(void) ATTR_WARN_UNUSED_RESULT;\r
+ /* Inline Functions: */\r
+ #if defined(USB_CAN_BE_BOTH)\r
+ static inline uint8_t USB_GetUSBModeFromUID(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;\r
static inline uint8_t USB_GetUSBModeFromUID(void)\r
{\r
- #if (defined(__AVR_AT90USB1287__) || defined(__AVR_AT90USB647__))\r
if (USBSTA & (1 << ID))\r
return USB_MODE_DEVICE;\r
else\r
return USB_MODE_HOST;\r
- #else\r
- return USB_MODE_DEVICE;\r
- #endif\r
}\r
+ #endif\r
+ \r
#endif\r
\r
/* Disable C linkage for C++ Compilers: */\r
#endif\r
\r
#endif\r
+\r
+/** @} */\r
projects / pub / USBasp.git / blobdiff