*/\r
\r
/** \file\r
- * \brief Common USB device mode definitions.\r
- *\r
- * This file contains common structures, function prototypes and macros related to USB device mode for all\r
- * architectures.\r
+ * \brief Common USB Device definitions for all architectures.\r
+ * \copydetails Group_Device\r
*\r
* \note This file should not be included directly. It is automatically included as needed by the USB driver\r
* dispatch header located in LUFA/Drivers/USB/USB.h.\r
\r
/** \ingroup Group_USB\r
* \defgroup Group_Device Device Management\r
+ * \brief USB Device management definitions for USB device mode.\r
*\r
* USB Device mode related definitions common to all architectures. This module contains definitions which\r
* are used when the USB controller is initialized in device mode.\r
\r
/* Includes: */\r
#include "../../../Common/Common.h"\r
+ #include "USBMode.h" \r
#include "StdDescriptors.h"\r
#include "USBInterrupt.h"\r
#include "Endpoint.h"\r
- \r
- #if (ARCH == ARCH_AVR8)\r
- #include "AVR8/Device.h"\r
- #endif\r
\r
/* Preprocessor Checks: */\r
#if !defined(__INCLUDE_FROM_USB_DRIVER)\r
#error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.\r
#endif\r
\r
+ /* Public Interface - May be used in end-application: */\r
+ /* Enums: */\r
+ /** Enum for the various states of the USB Device state machine. Only some states are\r
+ * implemented in the LUFA library - other states are left to the user to implement.\r
+ *\r
+ * For information on each possible USB device state, refer to the USB 2.0 specification.\r
+ *\r
+ * \see \ref USB_DeviceState, which stores the current device state machine state.\r
+ */\r
+ enum USB_Device_States_t\r
+ {\r
+ DEVICE_STATE_Unattached = 0, /**< Internally implemented by the library. This state indicates\r
+ * that the device is not currently connected to a host.\r
+ */\r
+ DEVICE_STATE_Powered = 1, /**< Internally implemented by the library. This state indicates\r
+ * that the device is connected to a host, but enumeration has not\r
+ * yet begun.\r
+ */\r
+ DEVICE_STATE_Default = 2, /**< Internally implemented by the library. This state indicates\r
+ * that the device's USB bus has been reset by the host and it is\r
+ * now waiting for the host to begin the enumeration process.\r
+ */\r
+ DEVICE_STATE_Addressed = 3, /**< Internally implemented by the library. This state indicates\r
+ * that the device has been addressed by the USB Host, but is not\r
+ * yet configured.\r
+ */\r
+ DEVICE_STATE_Configured = 4, /**< May be implemented by the user project. This state indicates\r
+ * that the device has been enumerated by the host and is ready\r
+ * for USB communications to begin.\r
+ */\r
+ DEVICE_STATE_Suspended = 5, /**< May be implemented by the user project. This state indicates\r
+ * that the USB bus has been suspended by the host, and the device\r
+ * should power down to a minimal power level until the bus is\r
+ * resumed.\r
+ */\r
+ };\r
+\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[in] 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[in] wIndex The language ID of the string to return if the \c wValue type indicates\r
+ * \ref DTYPE_String, otherwise zero for standard descriptors, or as defined in a\r
+ * class-specific standards.\r
+ * \param[out] DescriptorAddress Pointer to the descriptor in memory. This should be set by the routine to\r
+ * the address of the descriptor.\r
+ * \param[out] MemoryAddressSpace A value from the \ref USB_DescriptorMemorySpaces_t enum to indicate the memory\r
+ * space in which the descriptor is stored. This parameter does not exist when one\r
+ * of the \c USE_*_DESCRIPTORS compile time options is used, or on architectures which\r
+ * use a unified address space.\r
+ *\r
+ * \note By default, the library expects all descriptors to be located in flash memory via the \c 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 \c USE_RAM_DESCRIPTORS or the\r
+ * \c USE_EEPROM_DESCRIPTORS tokens may be defined in the project makefile and passed to the compiler by the -D\r
+ * switch.\r
+ *\r
+ * \return Size in bytes of the descriptor if it exists, zero or \ref NO_DESCRIPTOR otherwise.\r
+ */\r
+ uint16_t CALLBACK_USB_GetDescriptor(const uint16_t wValue,\r
+ const uint8_t wIndex,\r
+ const void** const DescriptorAddress\r
+ #if (defined(ARCH_HAS_MULTI_ADDRESS_SPACE) || defined(__DOXYGEN__)) && \\r
+ !(defined(USE_FLASH_DESCRIPTORS) || defined(USE_EEPROM_DESCRIPTORS) || defined(USE_RAM_DESCRIPTORS))\r
+ , uint8_t* MemoryAddressSpace\r
+ #endif\r
+ ) ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3);\r
+\r
+ /* Architecture Includes: */\r
+ #if (ARCH == ARCH_AVR8)\r
+ #include "AVR8/Device_AVR8.h"\r
+ #elif (ARCH == ARCH_UC3)\r
+ #include "UC3/Device_UC3.h"\r
+ #endif\r
+\r
#endif\r
\r
/** @} */\r
projects / pub / USBasp.git / blobdiff