USB_IsConnected is now cleared before the USB_Disconnect() event is fired in response...

[pub/lufa.git] / LUFA / Drivers / USB / HighLevel / Events.h

diff --git a/LUFA/Drivers/USB/HighLevel/Events.h b/LUFA/Drivers/USB/HighLevel/Events.h
index e65352e..2044a50 100644 (file)
--- a/LUFA/Drivers/USB/HighLevel/Events.h
+++ b/LUFA/Drivers/USB/HighLevel/Events.h
@@ -38,7 +38,8 @@
  *\r
  *  Events can be hooked by the user application by declaring a handler function with the same name and parameters\r
  *  listed here. If an event with no user-associated handler is fired within the library, it by default maps to an\r
  *\r
  *  Events can be hooked by the user application by declaring a handler function with the same name and parameters\r
  *  listed here. If an event with no user-associated handler is fired within the library, it by default maps to an\r

- *  internal empty stub function. This is achieved through the use of the GCC compiler's "alias" attribute.\r
+ *  internal empty stub function. This trasparent hook system is achieved through the use of the GCC compiler's\r
+ *  "alias" attribute.\r

  *\r
  *  Each event must only have one associated event handler, but can be raised by multiple sources.\r
  *\r
  *\r
  *  Each event must only have one associated event handler, but can be raised by multiple sources.\r
  *\r


@@ -63,23 +64,24 @@
                /* Pseudo-Functions for Doxygen: */\r
                #if !defined(INCLUDE_FROM_EVENTS_C) || defined(__DOXYGEN__)\r
                        /** Event for VBUS level change. This event fires when the VBUS line of the USB AVR changes from\r
                /* Pseudo-Functions for Doxygen: */\r
                #if !defined(INCLUDE_FROM_EVENTS_C) || defined(__DOXYGEN__)\r
                        /** Event for VBUS level change. This event fires when the VBUS line of the USB AVR changes from\r

-                        *  high to low or vice-versa.\r
+                        *  high to low or vice-versa, before the new VBUS level is sampled and the appropriate action\r
+                        *  taken.\r

                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r
                        void EVENT_USB_VBUSChange(void);\r
 \r
                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r
                        void EVENT_USB_VBUSChange(void);\r
 \r

-                       /** Event for VBUS attachment. This event fires when the VBUS line of the USB AVR changes from\r
-                        *  low to high, signalling the attachment of the USB device to a host, before the enumeration\r
-                        *  process has begun.\r
+                       /** Event for VBUS attachment. On the AVR models with a dedicated VBUS pin, this event fires when\r
+                        *  the VBUS line of the USB AVR changes from low to high (after the VBUS events have been handled),\r
+                        *  signalling the attachment of the USB device to a host, before the enumeration process has begun.\r

                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r
                        void EVENT_USB_VBUSConnect(void);\r
 \r
                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r
                        void EVENT_USB_VBUSConnect(void);\r
 \r

-                       /** Event for VBUS detachment. This event fires when the VBUS line of the USB AVR changes from\r
-                        *  high to low, signalling the USB device has been removed from a host whether it has been enumerated\r
-                        *  or not.\r
+                       /** Event for VBUS attachment. On the AVR models with a dedicated VBUS pin, this event fires when\r
+                        *  the VBUS line of the USB AVR changes from high to low (after the VBUS events have been handled),\r
+                        *  signalling the detatchment of the USB device from a host, regardless of its enumeration state.\r

                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r
                         *\r
                         *  \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
                         */\r


@@ -132,7 +134,8 @@
 \r
                        /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role\r
                         *  mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires\r
 \r
                        /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role\r
                         *  mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires\r

-                        *  before the mode is switched to the newly indicated mode.\r
+                        *  before the mode is switched to the newly indicated mode but after the \ref USB_Disconnect event has\r
+                        *  fired (if connected before the role change).\r

                         *\r
                         *  \note This event only exists on USB AVR models which support dual role modes.\r
                         *\r
                         *\r
                         *  \note This event only exists on USB AVR models which support dual role modes.\r
                         *\r


@@ -233,7 +236,9 @@
 \r
                        /** Event for USB suspend. This event fires when a the USB host suspends the device by halting its\r
                         *  transmission of Start Of Frame pulses to the device. This is generally hooked in order to move\r
 \r
                        /** Event for USB suspend. This event fires when a the USB host suspends the device by halting its\r
                         *  transmission of Start Of Frame pulses to the device. This is generally hooked in order to move\r

-                        *  the device over to a low power state until the host wakes up the device.\r
+                        *  the device over to a low power state until the host wakes up the device. If the USB interface is\r
+                        *  enumerated with the \ref USB_OPT_AUTO_PLL option set, the library will automatically suspend the\r
+                        *  USB PLL before the event is fired to save power.\r

                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r
                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r


@@ -245,7 +250,8 @@
                        /** Event for USB wake up. This event fires when a the USB interface is suspended while in device\r
                         *  mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally\r
                         *  hooked to pull the user application out of a lowe power state and back into normal operating\r
                        /** Event for USB wake up. This event fires when a the USB interface is suspended while in device\r
                         *  mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally\r
                         *  hooked to pull the user application out of a lowe power state and back into normal operating\r

-                        *  mode.\r
+                        *  mode. If the USB interface is enumerated with the \ref USB_OPT_AUTO_PLL option set, the library\r
+                        *  will automatically restart the USB PLL before the event is fired.\r

                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r
                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r


@@ -254,11 +260,9 @@
                         */\r
                        void EVENT_USB_WakeUp(void);\r
 \r
                         */\r
                        void EVENT_USB_WakeUp(void);\r
 \r

-                       /** Event for USB interface reset. This event fires when a the USB interface is in device mode, and\r
-                        *  a the USB host requests that the device reset its interface. This is generally hooked so that\r
-                        *  the USB control endpoint can be switched to interrupt driven mode, by selecting it and calling\r
-                        *  USB_INT_Enable(ENDPOINT_INT_SETUP). Before this event fires, all device endpoints are reset and\r
-                        *  disabled.\r
+                       /** Event for USB interface reset. This event fires when the USB interface is in device mode, and\r
+                        *  a the USB host requests that the device reset its interface. This event fires after the control\r
+                        *  endpoint has been automatically configured by the library.\r

                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r
                         *\r
                         *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
                         *        \ref Group_USBManagement documentation).\r