Commit 5e731905 authored by Dean Camera's avatar Dean Camera
Browse files

Start update of documentation to support possible multiple architectures in...

Start update of documentation to support possible multiple architectures in the future - alter \file documentation to automatically copy in the module documentation where possible.
parent 1daa5e16
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB host pipe management definitions.
*
* This file contains structures, function prototypes and macros related to the management of the device's
* data pipes when the library is initialized in USB host mode.
* \brief USB Pipe definitions for the AVR8 microcontrollers.
* \copydetails Group_PipeManagement_AVR8
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_PipeRW
* \defgroup Group_PipeRW_AVR8 Pipe Data Reading and Writing (AVR8)
* \brief USB Pipe definitions for the AVR8 microcontrollers.
*
* Functions, macros, variables, enums and types related to data reading and writing from and to pipes.
*/
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB low level USB controller definitions (AVR8)
*
* This file contains structures, function prototypes and macros related to the low level configuration of the
* USB controller, to start, stop and reset the USB library core.
* \brief USB Controller definitions for the AVR8 microcontrollers.
* \copydetails Group_USBManagement_AVR8
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_USBManagement
* \defgroup Group_USBManagement_AVR8 USB Interface Management (AVR8)
* \brief USB Controller definitions for the AVR8 microcontrollers.
*
* Functions, macros, variables, enums and types related to the setup and management of the USB interface.
*
......@@ -82,7 +81,7 @@
#endif
#if !defined(F_CLOCK)
#error F_CLOCK is not defined. You must define F_CLOCK to the frequency of the unprescaled input clock in your project makefile.
#error F_CLOCK is not defined. You must define F_CLOCK to the frequency of the unprescaled USB controller clock in your project makefile.
#endif
#if (F_CLOCK == 8000000)
......
......@@ -29,7 +29,7 @@
*/
/** \file
* \brief USB controller interrupt service routine management (AVR8)
* \brief USB Controller Interrupt definitions for the AVR8 microcontrollers.
*
* This file contains definitions required for the correct handling of low level USB service routine interrupts
* from the USB controller.
......@@ -63,11 +63,11 @@
#define USB_INT_IsEnabled(int) ((USB_INT_GET_EN_REG(int) & USB_INT_GET_EN_MASK(int)) ? true : false)
#define USB_INT_HasOccurred(int) ((USB_INT_GET_INT_REG(int) & USB_INT_GET_INT_MASK(int)) ? true : false)
#define USB_INT_GET_EN_REG(a, b, c, d) a
#define USB_INT_GET_EN_MASK(a, b, c, d) b
#define USB_INT_GET_INT_REG(a, b, c, d) c
#define USB_INT_GET_INT_MASK(a, b, c, d) d
#define USB_INT_GET_EN_REG(EnableReg, EnableMask, FlagReg, FlagMask) EnableReg
#define USB_INT_GET_EN_MASK(EnableReg, EnableMask, FlagReg, FlagMask) EnableMask
#define USB_INT_GET_INT_REG(EnableReg, EnableMask, FlagReg, FlagMask) FlagReg
#define USB_INT_GET_INT_MASK(EnableReg, EnableMask, FlagReg, FlagMask) FlagMask
#define USB_INT_VBUS USBCON, (1 << VBUSTE) , USBINT, (1 << VBUSTI)
#define USB_INT_IDTI USBCON, (1 << IDTE) , USBINT, (1 << IDTI)
#define USB_INT_WAKEUPI UDIEN , (1 << WAKEUPE), UDINT , (1 << WAKEUPI)
......
......@@ -29,11 +29,8 @@
*/
/** \file
* \brief Configuration descriptor parser API.
*
* This section of the library gives a friendly API which can be used in host applications to easily
* parse an attached device's configuration descriptor so that endpoint, interface and other descriptor
* data can be extracted and used as needed.
* \brief USB Configuration Descriptor definitions.
* \copydetails Group_ConfigDescriptorParser
*
* \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.
......@@ -41,8 +38,11 @@
/** \ingroup Group_Descriptors
* \defgroup Group_ConfigDescriptorParser Configuration Descriptor Parser
* \brief USB Configuration Descriptor definitions.
*
* Functions, macros, variables, enums and types related to the parsing of Configuration Descriptors.
* This section of the library gives a friendly API which can be used in host applications to easily
* parse an attached device's configuration descriptor so that endpoint, interface and other descriptor
* data can be extracted and used as needed.
*
* @{
*/
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief Common USB device mode definitions.
*
* This file contains common structures, function prototypes and macros related to USB device mode for all
* architectures.
* \brief Common USB Device definitions for all architectures.
* \copydetails Group_Device
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_USB
* \defgroup Group_Device Device Management
* \brief Common USB Device definitions for all architectures.
*
* USB Device mode related definitions common to all architectures. This module contains definitions which
* are used when the USB controller is initialized in device mode.
......@@ -65,6 +64,41 @@
#error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
#endif
/* Public Interface - May be used in end-application: */
/* Function Prototypes: */
/** Function to retrieve a given descriptor's size and memory location from the given descriptor type value,
* index and language ID. This function MUST be overridden in the user application (added with full, identical
* prototype and name so that the library can call it to retrieve descriptor data.
*
* \param[in] wValue The type of the descriptor to retrieve in the upper byte, and the index in the
* lower byte (when more than one descriptor of the given type exists, such as the
* case of string descriptors). The type may be one of the standard types defined
* in the DescriptorTypes_t enum, or may be a class-specific descriptor type value.
* \param[in] wIndex The language ID of the string to return if the \c wValue type indicates
* \ref DTYPE_String, otherwise zero for standard descriptors, or as defined in a
* class-specific standards.
* \param[out] DescriptorAddress Pointer to the descriptor in memory. This should be set by the routine to
* the address of the descriptor.
* \param[out] MemoryAddressSpace A value from the \ref USB_DescriptorMemorySpaces_t enum to indicate the memory
* space in which the descriptor is stored. This parameter does not exist when one
* of the \c USE_*_DESCRIPTORS compile time options is used.
*
* \note By default, the library expects all descriptors to be located in flash memory via the \c PROGMEM attribute.
* If descriptors should be located in RAM or EEPROM instead (to speed up access in the case of RAM, or to
* allow the descriptors to be changed dynamically at runtime) either the \c USE_RAM_DESCRIPTORS or the
* \c USE_EEPROM_DESCRIPTORS tokens may be defined in the project makefile and passed to the compiler by the -D
* switch.
*
* \return Size in bytes of the descriptor if it exists, zero or \ref NO_DESCRIPTOR otherwise.
*/
uint16_t CALLBACK_USB_GetDescriptor(const uint16_t wValue,
const uint8_t wIndex,
const void** const DescriptorAddress
#if !defined(USE_FLASH_DESCRIPTORS) && !defined(USE_EEPROM_DESCRIPTORS) && !defined(USE_RAM_DESCRIPTORS)
, uint8_t* MemoryAddressSpace
#endif
) ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3);
#endif
/** @} */
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB device endpoint management definitions.
*
* This file contains structures, function prototypes and macros related to the management of the device's
* data endpoints when the library is initialized in USB device mode.
* \brief Common USB Endpoint definitions for all architectures.
* \copydetails Group_EndpointManagement
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_EndpointManagement
* \defgroup Group_EndpointRW Endpoint Data Reading and Writing
* \brief Common USB Endpoint definitions for all architectures.
*
* Functions, macros, variables, enums and types related to data reading and writing from and to endpoints.
*/
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB device endpoint stream function definitions.
*
* This file contains structures, function prototypes and macros related to the sending and receiving of
* arbitrary data streams through the device's data endpoints when the library is initialized in USB device mode.
* \brief Endpoint data stream transmission and reception management.
* \copydetails Group_EndpointStreamRW
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_EndpointRW
* \defgroup Group_EndpointStreamRW Read/Write of Multi-Byte Streams
* \brief Endpoint data stream transmission and reception management.
*
* Functions, macros, variables, enums and types related to data reading and writing of data streams from
* and to endpoints.
......
......@@ -29,19 +29,8 @@
*/
/** \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.
......@@ -49,6 +38,7 @@
/** \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
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB host mode definitions.
*
* USB Host mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in host mode.
* \brief Common USB Host definitions for all architectures.
* \copydetails Group_Host
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_USB
* \defgroup Group_Host Host Management
* \brief Common USB Host definitions for all architectures.
*
* USB Host mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in host mode.
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB OTG mode definitions.
*
* This file contains structures, function prototypes and macros related to USB OTG mode, where two USB devices
* may be linked directly together and exchange host/device roles as needed.
* \brief Common USB OTG definitions for all architectures.
* \copydetails Group_OTG
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_USB
* \defgroup Group_OTG USB On The Go (OTG) Management
* \brief Common USB OTG definitions for all architectures.
*
* This module contains macros for embedded USB hosts with dual role On The Go capabilities, for managing role
* exchange. OTG is a way for two USB dual role devices to talk to one another directly without fixed device/host
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB host pipe management definitions.
*
* This file contains structures, function prototypes and macros related to the management of the device's
* data pipes when the library is initialized in USB host mode.
* \brief Common USB Pipe definitions for all architectures.
* \copydetails Group_PipeManagement
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_PipeManagement
* \defgroup Group_PipeRW Pipe Data Reading and Writing
* \brief Common USB Pipe definitions for all architectures.
*
* Functions, macros, variables, enums and types related to data reading and writing from and to pipes.
*/
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB host pipe stream function definitions.
*
* This file contains structures, function prototypes and macros related to the sending and receiving of
* arbitrary data streams through the device's data pipes when the library is initialized in USB host mode.
* \brief Pipe data stream transmission and reception management.
* \copydetails Group_PipeStreamRW
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_PipeRW
* \defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams
* \brief Pipe data stream transmission and reception management.
*
* Functions, macros, variables, enums and types related to data reading and writing of data streams from
* and to pipes.
......
......@@ -29,16 +29,16 @@
*/
/** \file
* \brief USB standard descriptor definitions.
*
* This file contains structures and macros for the easy creation of standard USB descriptors in USB device projects.
* \brief Common USB Descriptor definitions for all architectures.
* \copydetails Group_StdDescriptors
*
* \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.
*/
/** \ingroup Group_USB
* \defgroup Group_Descriptors USB Descriptors
* \defgroup Group_StdDescriptors USB Descriptors
* \brief Common USB Descriptor definitions for all architectures.
*
* Standard USB device descriptor defines and retrieval routines, for USB devices. This module contains
* structures and macros for the easy creation of standard USB descriptors in USB device projects.
......
......@@ -30,8 +30,7 @@
/** \file
* \brief USB control endpoint request definitions.
*
* This file contains structures and macros for the easy creation and parsing of standard USB control requests.
* \copydetails Group_StdRequest
*
* \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.
......@@ -39,6 +38,7 @@
/** \ingroup Group_USB
* \defgroup Group_StdRequest Standard USB Requests
* \brief USB control endpoint request definitions.
*
* This module contains definitions for the various control request parameters, so that the request
* details (such as data direction, request recipient, etc.) can be extracted via masking.
......
......@@ -29,10 +29,8 @@
*/
/** \file
* \brief USB low level USB controller definitions.
*
* This file contains structures, function prototypes and macros related to the low level configuration of the
* USB controller, to start, stop and reset the USB library core.
* \brief Common USB Controller definitions for all architectures.
* \copydetails Group_USBManagement
*
* \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.
......@@ -40,6 +38,7 @@
/** \ingroup Group_USB
* \defgroup Group_USBManagement USB Interface Management
* \brief Common USB Controller definitions for all architectures.
*
* Functions, macros, variables, enums and types related to the setup and management of the USB interface.
*
......
......@@ -29,11 +29,8 @@
*/
/** \file
* \brief USB mode and capability macros.
*
* This file defines macros indicating the type of USB controller the library is being compiled for, and its
* capabilities. These macros may then be referenced in the user application to selectively enable or disable
* code sections depending on if they are defined or not.
* \brief USB mode and feature support definitions.
* \copydetails Group_USBMode
*
* \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.
......@@ -41,11 +38,15 @@
/** \ingroup Group_USB
* \defgroup Group_USBMode USB Mode Tokens
* \brief USB mode and feature support definitions.
*
* This file defines macros indicating the type of USB controller the library is being compiled for, and its
* capabilities. These macros may then be referenced in the user application to selectively enable or disable
* code sections depending on if they are defined or not.
*
* After the inclusion of the master USB driver header, one or more of the following
* tokens may be defined, to allow the user code to conditionally enable or disable
* code based on the USB controller family and allowable USB modes. These tokens may
* be tested against to eliminate code relating to a USB mode which is not enabled for
* After the inclusion of the master USB driver header, one or more of the following tokens may be defined, to
* allow the user code to conditionally enable or disable code based on the USB controller family and allowable
* USB modes. These tokens may be tested against to eliminate code relating to a USB mode which is not enabled for
* the given compilation.
*
* @{
......
......@@ -120,17 +120,17 @@
* \section Sec_SummaryUSBDeviceTokens USB Device Mode Driver Related Tokens
* This section describes compile tokens which affect USB driver stack of the LUFA library when used in Device mode.
*
* <b>USE_RAM_DESCRIPTORS</b> - ( \ref Group_Descriptors ) \n
* <b>USE_RAM_DESCRIPTORS</b> - ( \ref Group_StdDescriptors ) \n
* Define this token to indicate to the USB driver that all device descriptors are stored in RAM, rather than being located in any one
* of the AVR's memory spaces. RAM descriptors may be desirable in applications where the descriptors need to be modified at runtime.
*
* <b>USE_FLASH_DESCRIPTORS</b> - ( \ref Group_Descriptors ) \n
* <b>USE_FLASH_DESCRIPTORS</b> - ( \ref Group_StdDescriptors ) \n
* Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's FLASH memory rather than RAM.
*
* <b>USE_EEPROM_DESCRIPTORS</b> - ( \ref Group_Descriptors ) \n
* <b>USE_EEPROM_DESCRIPTORS</b> - ( \ref Group_StdDescriptors ) \n
* Similar to USE_RAM_DESCRIPTORS, but all descriptors are stored in the AVR's EEPROM memory rather than RAM.
*
* <b>NO_INTERNAL_SERIAL</b> - ( \ref Group_Descriptors ) \n
* <b>NO_INTERNAL_SERIAL</b> - ( \ref Group_StdDescriptors ) \n
* Some AVR models contain a unique 20-digit serial number which can be used as the device serial number, while in device mode. This
* allows the host to uniquely identify the device regardless of if it is moved between USB ports on the same computer, allowing
* allocated resources (such as drivers, COM Port number allocations) to be preserved. This is not needed in many apps, and so the
......
......@@ -12,12 +12,15 @@
* hardware). This might be required because the device does not have any physical user input, or simply
* just to streamline the device upgrade process on the host PC.
*
* The following C code snippet may be used to enter the bootloader upon request by the user application.
* The following C code snippets may be used to enter the bootloader upon request by the user application.
* By using the watchdog to physically reset the controller, it is ensured that all system hardware is
* completely reset to their defaults before the bootloader is run. This is important; since bootloaders
* are written to occupy a very limited space, they usually make assumptions about the register states based
* on the default values after a hard-reset of the chip.
*
* \section Sec_SoftareBootAVR8 AVR8 Architecture
* The following software bootloader jump code is written for the AVR8 architecture.
*
* \code
* #include <avr/wdt.h>
* #include <avr/io.h>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment