X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/7d4cccc22d60125fac111819df48af1873d11018..03ee87b35abdb8b92e8b55ec040fa943f9a6786c:/LUFA/Drivers/USB/LowLevel/LowLevel.h?ds=inline diff --git a/LUFA/Drivers/USB/LowLevel/LowLevel.h b/LUFA/Drivers/USB/LowLevel/LowLevel.h index 94d8c83c9..dc01d24e5 100644 --- a/LUFA/Drivers/USB/LowLevel/LowLevel.h +++ b/LUFA/Drivers/USB/LowLevel/LowLevel.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - 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 + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + 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 software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -28,10 +28,12 @@ this software. */ -/** \file +/** \ingroup Group_USB + * @defgroup Group_USBManagement USB Interface Management * - * Main low level USB driver. This module manages the low level initialization and shut down of the USB AVR's - * USB interface in either device or (if supported) host mode. + * Functions, macros, variables, enums and types related to the setup and management of the USB interface. + * + * @{ */ #ifndef __USBLOWLEVEL_H__ @@ -69,29 +71,32 @@ /* Preprocessor Checks and Defines: */ #if !defined(F_CLOCK) - #error F_CLOCK is not defined. You must device F_CLOCK to the frequency of the unprescaled input clock in your project makefile. - #define F_CLOCK 0 + #error F_CLOCK is not defined. You must define F_CLOCK to the frequency of the unprescaled input clock in your project makefile. #endif #if (F_CLOCK == 8000000) - #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__)) + #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \ + defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \ + defined(__AVR_ATmega32U2__)) #define USB_PLL_PSC 0 - #elif (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || \ - defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__) || \ - defined(__AVR_ATmega32U6__)) - #define USB_PLL_PSC ((1 << PLLP1) | (1 << PLLP0)) #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_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)) - #elif (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__)) + #if (defined(__AVR_AT90USB82__) || defined(__AVR_AT90USB162__) || \ + defined(__AVR_ATmega8U2__) || defined(__AVR_ATmega16U2__) || \ + defined(__AVR_ATmega32U2__)) #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 @@ -101,27 +106,23 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Mode mask for the USB_CurrentMode global. This indicates that the USB interface is currently not + /** Mode mask for the \ref USB_CurrentMode global. This indicates that the USB interface is currently not * initialized into any mode. */ #define USB_MODE_NONE 0 - /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the + /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the * USB interface is or should be initialized in the USB device mode. */ #define USB_MODE_DEVICE 1 - - #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) - /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the - * USB interface is or should be initialized in the USB host mode. - * - * \note This token is not available on AVR models which do not support host mode. - */ - #define USB_MODE_HOST 2 - #endif + + /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the + * USB interface is or should be initialized in the USB host mode. + */ + #define USB_MODE_HOST 2 #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__) - /** Mode mask for the the USB_Init() function. This indicates that the USB interface should be + /** Mode mask for the the \ref USB_Init() function. This indicates that the USB interface should be * initialized into whatever mode the UID pin of the USB AVR indicates, and that the device * should swap over its mode when the level of the UID pin changes during operation. * @@ -130,27 +131,27 @@ #define USB_MODE_UID 3 #endif - /** Regulator disable option mask for USB_Init(). This indicates that the internal 3.3V USB data pad + /** 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 USB_Init(). This indicates that the internal 3.3V USB data pad + /** 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) - /** Manual PLL control option mask for USB_Init(). This indicates to the library that the user application + /** 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 USB_Init(). This indicates to the library that the library should + /** 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. */ @@ -158,36 +159,29 @@ /** Mask for a CONTROL type endpoint or pipe. * - * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions. + * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ - #define EP_TYPE_CONTROL 0b00 + #define EP_TYPE_CONTROL 0x00 /** Mask for an ISOCHRONOUS type endpoint or pipe. * - * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions. + * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ - #define EP_TYPE_ISOCHRONOUS 0b01 + #define EP_TYPE_ISOCHRONOUS 0x01 /** Mask for a BULK type endpoint or pipe. * - * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions. + * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ - #define EP_TYPE_BULK 0b10 + #define EP_TYPE_BULK 0x02 /** Mask for an INTERRUPT type endpoint or pipe. * - * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions. - */ - #define EP_TYPE_INTERRUPT 0b11 - - /** Mask for determining the type of an endpoint or pipe. This should then be compared with the - * EP_TYPE_* macros elsewhere in this module to determine the exact type of the endpoint or pipe. - * - * \note See Endpoint.h and Pipe.h headers for endpoint/pipe functions. + * \note See \ref Group_EndpointManagement and \ref Group_PipeManagement for endpoint/pipe functions. */ - #define EP_TYPE_MASK 0b11 + #define EP_TYPE_INTERRUPT 0x03 - #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__) + #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. * @@ -197,8 +191,8 @@ #endif /** Detaches the device from the USB bus. This has the effect of removing the device from any - * host if, ceasing USB communications. If no host is present, this prevents any host from - * enumerating the device once attached until USB_Attach() is called. + * 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. */ #define USB_Detach() MACROS{ UDCON |= (1 << DETACH); }MACROE @@ -218,7 +212,7 @@ * is not received or acknowledged within this time period, the stream function will fail. * * This value may be overridden in the user project makefile as the value of the - * USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch. + * \ref USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch. */ #define USB_STREAM_TIMEOUT_MS 100 #endif @@ -234,14 +228,14 @@ * Calling this function when the USB interface is already initialized will cause a complete USB * interface reset and re-enumeration. * - * \param Mode This is a mask indicating what mode the USB interface is to be initialized to. - * Valid mode masks are USB_MODE_DEVICE, USB_MODE_HOST or USB_MODE_UID. + * \param[in] Mode This is a mask indicating what mode the USB interface is to be initialized to. + * Valid mode masks are \ref USB_MODE_DEVICE, \ref USB_MODE_HOST or \ref USB_MODE_UID. * - * \param Options Mask indicating the options which should be used when initializing the USB - * interface to control the USB interface's behaviour. This should be comprised of - * 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. + * \param[in] Options Mask indicating the options which should be used when initializing the USB + * interface to control the USB interface's behaviour. This should be comprised of + * 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. * * \note To reduce the FLASH requirements of the library if only device or host mode is required, * this can be statically set via defining the token USB_DEVICE_ONLY for device mode or @@ -278,7 +272,7 @@ /** 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 USB_Init() function. + * is restarted with the \ref USB_Init() function. */ void USB_ShutDown(void); @@ -289,11 +283,11 @@ /* Enums: */ /** Enum for error codes relating to the powering on of the USB interface. These error codes are - * used in the ErrorCode parameter value of the USB_PowerOnFail event. + * used in the ErrorCode parameter value of the \ref EVENT_USB_InitFailure() event. */ - enum USB_PowerOnErrorCodes_t + enum USB_InitErrorCodes_t { - POWERON_ERROR_NoUSBModeSpecified = 0, /**< Indicates that USB_Init() was called with an + USB_INITERROR_NoUSBModeSpecified = 0, /**< Indicates that \ref USB_Init() was called with an * invalid or missing Mode parameter. */ }; @@ -307,36 +301,24 @@ * changed in value. */ extern volatile uint8_t USB_CurrentMode; + #elif defined(USB_HOST_ONLY) + #define USB_CurrentMode USB_MODE_HOST + #elif defined(USB_DEVICE_ONLY) + #define USB_CurrentMode USB_MODE_DEVICE #endif #if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__) - extern volatile uint8_t USB_Options; - /** Indicates the current USB options that the USB interface was initialized with when USB_Init() + /** 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 - /* Throwable Events: */ - /** This module raises the USB_Disconnect event if the USB interface is reset (such as during a mode - * change while in UID mode) while the USB interface is connected to a device when in host mode, or - * a host while in device mode. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_Disconnect); - - #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__) - /** This module raises the Power On Failure event when an error occurs while initializing the USB - * interface. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_PowerOnFail); - #endif - /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */ @@ -344,7 +326,7 @@ #define USB_PLL_Off() MACROS{ PLLCSR = 0; }MACROE #define USB_PLL_IsReady() ((PLLCSR & (1 << PLOCK)) ? true : false) - #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) + #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) #define USB_REG_On() MACROS{ UHWCON |= (1 << UVREGE); }MACROE #define USB_REG_Off() MACROS{ UHWCON &= ~(1 << UVREGE); }MACROE #else @@ -358,14 +340,14 @@ #define USB_CLK_Freeze() MACROS{ USBCON |= (1 << FRZCLK); }MACROE #define USB_CLK_Unfreeze() MACROS{ USBCON &= ~(1 << FRZCLK); }MACROE - #define USB_Interface_Enable() MACROS{ USBCON |= (1 << USBE); }MACROE - #define USB_Interface_Disable() MACROS{ USBCON &= ~(1 << USBE); }MACROE - #define USB_Interface_Reset() MACROS{ uint8_t Temp = USBCON; USBCON = (Temp & ~(1 << USBE)); \ + #define USB_Controller_Enable() MACROS{ USBCON |= (1 << USBE); }MACROE + #define USB_Controller_Disable() MACROS{ USBCON &= ~(1 << USBE); }MACROE + #define USB_Controller_Reset() MACROS{ const uint8_t Temp = USBCON; USBCON = (Temp & ~(1 << USBE)); \ USBCON = (Temp | (1 << USBE)); }MACROE /* Inline Functions: */ #if defined(USB_CAN_BE_BOTH) - static inline uint8_t USB_GetUSBModeFromUID(void) ATTR_WARN_UNUSED_RESULT; + 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)) @@ -383,3 +365,5 @@ #endif #endif + +/** @} */