Move new Class Driver powered demos to a new ClassDriver subdirectory, re-add old...

[pub/USBasp.git] / LUFA / Drivers / USB / LowLevel / Device.h

diff --git a/LUFA/Drivers/USB/LowLevel/Device.h b/LUFA/Drivers/USB/LowLevel/Device.h
index 8a2ee00..31d612c 100644 (file)
--- a/LUFA/Drivers/USB/LowLevel/Device.h
+++ b/LUFA/Drivers/USB/LowLevel/Device.h
@@ -27,17 +27,12 @@
   arising out of or in connection with the use or performance of\r
   this software.\r
 */\r
   arising out of or in connection with the use or performance of\r
   this software.\r
 */\r

-\r
-/** \file\r
- *\r
- *  USB Device mode related macros and enums. This module contains macros and enums which are used when\r
- *  the USB controller is initialized in device mode.\r
- */\r

  \r
 /** \ingroup Group_USB\r
  *  @defgroup Group_Device Device Management\r
  *\r
  \r
 /** \ingroup Group_USB\r
  *  @defgroup Group_Device Device Management\r
  *\r

- *  Functions, macros, variables, enums and types related to the management of a USB device when in Device mode.\r
+ *  USB Device mode related macros and enums. This module contains macros and enums which are used when\r
+ *  the USB controller is initialized in device mode.\r

  *\r
  *  @{\r
  */\r
  *\r
  *  @{\r
  */\r


@@ -56,7 +51,7 @@
        /* Public Interface - May be used in end-application: */\r
                /* Macros: */\r
                        #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__)\r
        /* Public Interface - May be used in end-application: */\r
                /* Macros: */\r
                        #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__)\r

-                               /** Mask for the Options parameter of the USB_Init() function. This indicates that the\r
+                               /** Mask for the Options parameter of the \ref USB_Init() function. This indicates that the\r

                                 *  USB interface should be initialized in low speed (1.5Mb/s) mode.\r
                                 *\r
                                 *  \note Low Speed mode is not available on all USB AVR models.\r
                                 *  USB interface should be initialized in low speed (1.5Mb/s) mode.\r
                                 *\r
                                 *  \note Low Speed mode is not available on all USB AVR models.\r


@@ -72,7 +67,7 @@
                         */\r
                        #define USB_DEVICE_OPT_FULLSPEED               (0 << 0)\r
                        \r
                         */\r
                        #define USB_DEVICE_OPT_FULLSPEED               (0 << 0)\r
                        \r

-               /* Psuedo-Function Macros: */\r
+               /* Pseudo-Function Macros: */\r

                        #if defined(__DOXYGEN__)\r
                                /** Sends a Remote Wakeup request to the host. This signals to the host that the device should\r
                                 *  be taken out of suspended mode, and communications should resume.\r
                        #if defined(__DOXYGEN__)\r
                                /** Sends a Remote Wakeup request to the host. This signals to the host that the device should\r
                                 *  be taken out of suspended mode, and communications should resume.\r


@@ -83,30 +78,30 @@
                                 *  \note This macro should only be used if the device has indicated to the host that it\r
                                 *        supports the Remote Wakeup feature in the device descriptors, and should only be\r
                                 *        issued if the host is currently allowing remote wakeup events from the device (i.e.,\r
                                 *  \note This macro should only be used if the device has indicated to the host that it\r
                                 *        supports the Remote Wakeup feature in the device descriptors, and should only be\r
                                 *        issued if the host is currently allowing remote wakeup events from the device (i.e.,\r

-                                *        the USB_RemoteWakeupEnabled flag is set, see DevChapter9.h documentation).\r
+                                *        the \ref USB_RemoteWakeupEnabled flag is set).\r

                                 *\r
                                 *\r

-                                *  \see StdDescriptors.h for more information on the RMWAKEUP feature and device descriptors.\r
+                                *  \see \ref Group_Descriptors for more information on the RMWAKEUP feature and device descriptors.\r

                                 */\r
                                static inline void USB_Device_SendRemoteWakeup(void);\r
                                \r
                                /** Indicates if a Remote Wakeup request is being sent to the host. This returns true if a\r
                                 *  remote wakeup is currently being sent, false otherwise.\r
                                 *\r
                                 */\r
                                static inline void USB_Device_SendRemoteWakeup(void);\r
                                \r
                                /** Indicates if a Remote Wakeup request is being sent to the host. This returns true if a\r
                                 *  remote wakeup is currently being sent, false otherwise.\r
                                 *\r

-                                *  This can be used in conjunction with the USB_Device_IsUSBSuspended() macro to determine if\r
+                                *  This can be used in conjunction with the \ref USB_Device_IsUSBSuspended() macro to determine if\r

                                 *  a sent RMWAKEUP request was accepted or rejected by the host.\r
                                 *\r
                                 *  \note This macro should only be used if the device has indicated to the host that it\r
                                 *        supports the Remote Wakeup feature in the device descriptors.\r
                                 *\r
                                 *  a sent RMWAKEUP request was accepted or rejected by the host.\r
                                 *\r
                                 *  \note This macro should only be used if the device has indicated to the host that it\r
                                 *        supports the Remote Wakeup feature in the device descriptors.\r
                                 *\r

-                                *  \see StdDescriptors.h for more information on the RMWAKEUP feature and device descriptors.\r
+                                *  \see \ref Group_Descriptors for more information on the RMWAKEUP feature and device descriptors.\r

                                 *\r
                                 *  \return Boolean true if no Remote Wakeup request is currently being sent, false otherwise\r
                                 */\r
                                static inline bool USB_Device_IsRemoteWakeupSent(void);\r
                                \r
                                 *\r
                                 *  \return Boolean true if no Remote Wakeup request is currently being sent, false otherwise\r
                                 */\r
                                static inline bool USB_Device_IsRemoteWakeupSent(void);\r
                                \r

-                               /** Indicates if the device is currently suspended by the host. While suspended, the device is\r
-                                *  to enter a low power state until resumed by the host. While suspended no USB traffic to or\r
-                                *  from the device can occur (except for Remote Wakeup requests).\r
+                               /** Indicates if the device is currently suspended by the host. Whilst suspended, the device is\r
+                                *  to enter a low power state until resumed by the host. No USB traffic to or from the device\r
+                                *  can occur (except for Remote Wakeup requests) during suspension by the host.\r

                                 *\r
                                 *  \return Boolean true if the USB communications have been suspended by the host, false otherwise.\r
                                 */\r
                                 *\r
                                 *  \return Boolean true if the USB communications have been suspended by the host, false otherwise.\r
                                 */\r


@@ -119,20 +114,31 @@
                                #define USB_Device_IsUSBSuspended()           ((UDINT &  (1 << SUSPI)) ? true : false)\r
                        #endif\r
 \r
                                #define USB_Device_IsUSBSuspended()           ((UDINT &  (1 << SUSPI)) ? true : false)\r
                        #endif\r
 \r

-               /* Enums: */\r
-                       /** Enum for the ErrorCode parameter of the USB_DeviceError event.\r
+               /* Function Prototypes: */\r
+                       /** Function to retrieve a given descriptor's size and memory location from the given descriptor type value,\r
+                        *  index and language ID. This function MUST be overridden in the user application (added with full, identical  \r
+                        *  prototype and name so that the library can call it to retrieve descriptor data.\r
+                        *\r
+                        *  \param wValue             The type of the descriptor to retrieve in the upper byte, and the index in the \r
+                        *                            lower byte (when more than one descriptor of the given type exists, such as the\r
+                        *                            case of string descriptors). The type may be one of the standard types defined\r
+                        *                            in the DescriptorTypes_t enum, or may be a class-specific descriptor type value.\r
+                        *  \param wIndex             The language ID of the string to return if the wValue type indicates DTYPE_String,\r
+                        *                            otherwise zero for standard descriptors, or as defined in a class-specific\r
+                        *                            standards.\r
+                        *  \param DescriptorAddress  Pointer to the descriptor in memory. This should be set by the routine to\r
+                        *                            the address of the descriptor.\r
+                        *\r
+                        *  \note By default, the library expects all descriptors to be located in flash memory via the PROGMEM attribute.\r
+                        *        If descriptors should be located in RAM or EEPROM instead (to speed up access in the case of RAM, or to\r
+                        *        allow the descriptors to be changed dynamically at runtime) either the USE_RAM_DESCRIPTORS or the \r
+                        *        USE_EEPROM_DESCRIPTORS tokens may be defined in the project makefile and passed to the compiler by the -D\r
+                        *        switch.\r

                         *\r
                         *\r

-                        *  \see Events.h for more information on this event.\r
+                        *  \return Size in bytes of the descriptor if it exists, zero or \ref NO_DESCRIPTOR otherwise\r

                         */\r
                         */\r

-                       enum USB_Device_ErrorCodes_t\r
-                       {\r
-                               DEVICE_ERROR_GetDescriptorNotHooked        = 0, /**< Indicates that the GetDescriptor() method\r
-                                                                                *   has not been hooked by the user application.\r
-                                                                                *\r
-                                                                                *   \see StdDescriptors.h for more information on\r
-                                                                                *        the GetDescriptor() method.\r
-                                                                                */\r
-                       };\r
+                       uint16_t CALLBACK_USB_GetDescriptor(const uint16_t wValue, const uint8_t wIndex, void** const DescriptorAddress)\r
+                                                                                   ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3);\r

 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r
 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r