AppConfigHeaders: Update several additional user projects to use configuration header...

[pub/USBasp.git] / LUFA / Drivers / USB / Core / Events.h

diff --git a/LUFA/Drivers/USB/Core/Events.h b/LUFA/Drivers/USB/Core/Events.h
index 4a3a1a1..8d627d4 100644 (file)
--- a/LUFA/Drivers/USB/Core/Events.h
+++ b/LUFA/Drivers/USB/Core/Events.h
@@ -1,13 +1,13 @@
 /*
              LUFA Library
 /*
              LUFA Library

-     Copyright (C) Dean Camera, 2011.
+     Copyright (C) Dean Camera, 2012.

 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*
 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*

-  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2012  Dean Camera (dean [at] fourwalledcubicle [dot] com)

 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted


@@ -29,19 +29,8 @@
 */
 
 /** \file
 */
 
 /** \file

- *  \brief USB controller events manager.
- *
- *  This file contains macros and functions relating to the management of library events, which are small
- *  pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from
- *  multiple places in the user or library code, which may or may not be inside an ISR, thus each handler
- *  should be written to be as small and fast as possible to prevent possible problems.
- *
- *  Events can be hooked by the user application by declaring a handler function with the same name and parameters
- *  listed here. If an event with no user-associated handler is fired within the library, it by default maps to an
- *  internal empty stub function.
- *
- *  Each event must only have one associated event handler, but can be raised by multiple sources by calling the
- *  event handler function (with any required event parameters).
+ *  \brief USB Event management definitions.
+ *  \copydetails Group_Events

  *
  *  \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.
  *
  *  \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.


@@ -49,6 +38,7 @@
 
 /** \ingroup Group_USB
  *  \defgroup Group_Events USB Events
 
 /** \ingroup Group_USB
  *  \defgroup Group_Events USB Events

+ *  \brief USB Event management definitions.

  *
  *  This module contains macros and functions relating to the management of library events, which are small
  *  pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from
  *
  *  This module contains macros and functions relating to the management of library events, which are small
  *  pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from


@@ -88,7 +78,7 @@
                        /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role
                         *  mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires
                         *  before the mode is switched to the newly indicated mode but after the \ref EVENT_USB_Device_Disconnect
                        /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role
                         *  mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires
                         *  before the mode is switched to the newly indicated mode but after the \ref EVENT_USB_Device_Disconnect

-                        *  event has fired (if connected before the role change).
+                        *  event has fired (if disconnected before the role change).

                         *
                         *  \note This event only exists on microcontrollers that support dual role USB modes.
                         *        \n\n
                         *
                         *  \note This event only exists on microcontrollers that support dual role USB modes.
                         *        \n\n


@@ -193,7 +183,10 @@
                         *  This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
                         *  two seconds) will prevent the device from enumerating correctly.
                         *
                         *  This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
                         *  two seconds) will prevent the device from enumerating correctly.
                         *

-                        *  \note For the smaller series 2 USB AVRs with limited USB controllers, VBUS is not available to the USB controller.
+                        *  \attention This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
+                        *             if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
+                        *
+                        *  \note For the microcontrollers with limited USB controller functionality, VBUS sensing is not available.

                         *        this means that the current connection state is derived from the bus suspension and wake up events by default,
                         *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state
                         *        needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
                         *        this means that the current connection state is derived from the bus suspension and wake up events by default,
                         *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state
                         *        needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by


@@ -201,9 +194,6 @@
                         *        and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
                         *        \n\n
                         *
                         *        and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
                         *        \n\n
                         *

-                        *  \note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
-                        *        if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
-                        *

                         *  \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
                         */
                        void EVENT_USB_Device_Connect(void);
                         *  \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
                         */
                        void EVENT_USB_Device_Connect(void);


@@ -211,6 +201,9 @@
                        /** Event for USB device disconnection. This event fires when the microcontroller is in USB Device mode and the device is
                         *  disconnected from a host, measured by a falling level on the microcontroller's VBUS sense pin.
                         *
                        /** Event for USB device disconnection. This event fires when the microcontroller is in USB Device mode and the device is
                         *  disconnected from a host, measured by a falling level on the microcontroller's VBUS sense pin.
                         *

+                        *  \attention This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
+                        *             if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
+                        *

                         *  \note For the microcontrollers with limited USB controllers, VBUS sense is not available to the USB controller.
                         *        this means that the current connection state is derived from the bus suspension and wake up events by default,
                         *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state
                         *  \note For the microcontrollers with limited USB controllers, VBUS sense is not available to the USB controller.
                         *        this means that the current connection state is derived from the bus suspension and wake up events by default,
                         *        which is not always accurate (host may suspend the bus while still connected). If the actual connection state


@@ -219,15 +212,12 @@
                         *        and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
                         *        \n\n
                         *
                         *        and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
                         *        \n\n
                         *

-                        *  \note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
-                        *        if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
-                        *

                         *  \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
                         */
                        void EVENT_USB_Device_Disconnect(void);
 
                        /** Event for control requests. This event fires when a the USB host issues a control request
                         *  \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
                         */
                        void EVENT_USB_Device_Disconnect(void);
 
                        /** Event for control requests. This event fires when a the USB host issues a control request

-                        *  to the mandatory device control endpoint (of address 0). This may either be a standard 
+                        *  to the mandatory device control endpoint (of address 0). This may either be a standard

                         *  request that the library may have a handler code for internally, or a class specific request
                         *  issued to the device which must be handled appropriately. If a request is not processed in the
                         *  user application via this event, it will be passed to the library for processing internally
                         *  request that the library may have a handler code for internally, or a class specific request
                         *  issued to the device which must be handled appropriately. If a request is not processed in the
                         *  user application via this event, it will be passed to the library for processing internally


@@ -259,7 +249,7 @@
                         *  This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
                         *  one second) will prevent the device from enumerating correctly.
                         *
                         *  This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
                         *  one second) will prevent the device from enumerating correctly.
                         *

-                        *  This event fires after the value of \ref USB_ConfigurationNumber has been changed.
+                        *  This event fires after the value of \ref USB_Device_ConfigurationNumber has been changed.

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