From 9cec85bfd92a77a97e7d12625897de2682dfacd7 Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Wed, 22 Apr 2009 14:28:55 +0000 Subject: Documentation enhancements to improve documentation cross-references. --- LUFA/Drivers/USB/Class/ConfigDescriptor.h | 8 +-- LUFA/Drivers/USB/Class/HIDParser.h | 28 +++++----- LUFA/Drivers/USB/HighLevel/Events.h | 36 +++++------- LUFA/Drivers/USB/HighLevel/StdDescriptors.h | 44 +++++++-------- LUFA/Drivers/USB/HighLevel/StdRequestType.h | 40 +++++++------- LUFA/Drivers/USB/HighLevel/StreamCallbacks.h | 2 +- LUFA/Drivers/USB/HighLevel/USBInterrupt.h | 6 +- LUFA/Drivers/USB/HighLevel/USBTask.h | 38 ++++++------- LUFA/Drivers/USB/LowLevel/DevChapter9.h | 8 +-- LUFA/Drivers/USB/LowLevel/Device.h | 18 +++--- LUFA/Drivers/USB/LowLevel/Endpoint.h | 81 ++++++++++++++------------- LUFA/Drivers/USB/LowLevel/Host.h | 14 ++--- LUFA/Drivers/USB/LowLevel/HostChapter9.h | 6 +- LUFA/Drivers/USB/LowLevel/LowLevel.h | 32 +++++------ LUFA/Drivers/USB/LowLevel/OTG.h | 4 +- LUFA/Drivers/USB/LowLevel/Pipe.h | 83 ++++++++++++++-------------- 16 files changed, 220 insertions(+), 228 deletions(-) (limited to 'LUFA/Drivers/USB') diff --git a/LUFA/Drivers/USB/Class/ConfigDescriptor.h b/LUFA/Drivers/USB/Class/ConfigDescriptor.h index 362a43e75..da38492ff 100644 --- a/LUFA/Drivers/USB/Class/ConfigDescriptor.h +++ b/LUFA/Drivers/USB/Class/ConfigDescriptor.h @@ -118,7 +118,7 @@ * for certain descriptors matching unique criteria. * * Comparator routines are passed in a single pointer named CurrentDescriptor, and should return a value - * of a member of the DSearch_Return_ErrorCodes_t enum. + * of a member of the \ref DSearch_Return_ErrorCodes_t enum. */ #define DESCRIPTOR_COMPARATOR(name) uint8_t DCOMP_##name (void* const CurrentDescriptor) @@ -137,7 +137,7 @@ * \param CurrConfigLoc Pointer to the current position in the configuration descriptor * \param ComparatorRoutine Name of the comparator search function to use on the configuration descriptor * - * \return Value of one of the members of the DSearch_Comp_Return_ErrorCodes_t enum + * \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum * * Usage Example: * \code @@ -166,7 +166,7 @@ #endif /* Enums: */ - /** Enum for return values of a descriptor comparator made with DESCRIPTOR_COMPARATOR. */ + /** Enum for return values of a descriptor comparator made with \ref DESCRIPTOR_COMPARATOR. */ enum DSearch_Return_ErrorCodes_t { DESCRIPTOR_SEARCH_Found = 0, /**< Current descriptor matches comparator criteria. */ @@ -174,7 +174,7 @@ DESCRIPTOR_SEARCH_NotFound = 2, /**< Current descriptor does not match comparator criteria. */ }; - /** Enum for return values of USB_GetNextDescriptorComp(). */ + /** Enum for return values of \ref USB_GetNextDescriptorComp(). */ enum DSearch_Comp_Return_ErrorCodes_t { DESCRIPTOR_SEARCH_COMP_Found = 0, /**< Configuration descriptor now points to descriptor which matches diff --git a/LUFA/Drivers/USB/Class/HIDParser.h b/LUFA/Drivers/USB/Class/HIDParser.h index f02f1fd09..49e57c295 100644 --- a/LUFA/Drivers/USB/Class/HIDParser.h +++ b/LUFA/Drivers/USB/Class/HIDParser.h @@ -114,7 +114,7 @@ /* Public Interface - May be used in end-application: */ /* Enums: */ - /** Enum for indicating what type of report item an entry in a HID_ReportInfo_t ReportItem array is */ + /** Enum for indicating what type of report item an entry in a \ref HID_ReportInfo_t ReportItem array is */ enum HID_ReportItemTypes_t { REPORT_ITEM_TYPE_In = 0, /**< Indicates that the item is an IN report type. */ @@ -122,16 +122,16 @@ REPORT_ITEM_TYPE_Feature = 2, /**< Indicates that the item is a FEATURE report type. */ }; - /** Enum for the possible error codes in the return value of the ProcessHIDReport() function */ + /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */ enum HID_Parse_ErrorCodes_t { HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */ - HID_PARSE_HIDStackOverflow = 1, /**< More than HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ + HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */ - HID_PARSE_InsufficientReportItems = 3, /**< More than HID_MAX_REPORTITEMS report items in the report. */ + HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */ HID_PARSE_UnexpectedEndCollection = 4, /**< END COLLECTION found without matching COLLECTION item. */ - HID_PARSE_InsufficientCollectionPaths = 5, /**< More than HID_MAX_COLLECTIONS collections in the report. */ - HID_PARSE_UsageStackOverflow = 6, /**< More than HID_USAGE_STACK_DEPTH usages listed in a row. */ + HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */ + HID_PARSE_UsageStackOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */ }; /* Type Defines: */ @@ -162,7 +162,7 @@ */ typedef struct CollectionPath { - uint8_t Type; /**< Collection type (for example "Generic Desktop"). */ + uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */ HID_Usage_t Usage; /**< Collection usage. */ struct CollectionPath* Parent; /**< Reference to parent collection, or NULL if root collection. */ } HID_CollectionPath_t; @@ -207,22 +207,22 @@ /* Function Prototypes: */ /** Function to process a given HID report returned from an attached device, and store it into a given - * HID_ReportInfo_t structure. + * \ref HID_ReportInfo_t structure. * * \param ReportData Buffer containing the device's HID report table * \param ReportSize Size in bytes of the HID report table - * \param ParserData Pointer to a HID_ReportInfo_t instance for the parser output + * \param ParserData Pointer to a \ref HID_ReportInfo_t instance for the parser output * - * \return A value in the HID_Parse_ErrorCodes_t enum + * \return A value in the \ref HID_Parse_ErrorCodes_t enum */ uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1, 3); /** Extracts the given report item's value out of the given HID report and places it into the Value - * member of the report item's HID_ReportItem_t structure. + * member of the report item's \ref HID_ReportItem_t structure. * * \param ReportData Buffer containing an IN or FEATURE report from an attached device - * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array + * \param ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array * * \returns Boolean true if the item to retrieve was located in the given report, false otherwise */ @@ -230,14 +230,14 @@ ATTR_NON_NULL_PTR_ARG(1, 2); /** Retrieves the given report item's value out of the Value member of the report item's - * HID_ReportItem_t structure and places it into the correct position in the HID report + * \ref HID_ReportItem_t structure and places it into the correct position in the HID report * buffer. The report buffer is assumed to have the appropriate bits cleared before calling * this function (i.e., the buffer should be explicitly cleared before report values are added). * * If the device has multiple HID reports, the report ID is set to the report ID of the given item. * * \param ReportData Buffer holding the current OUT report data - * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array + * \param ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array */ void USB_SetHIDReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem) ATTR_NON_NULL_PTR_ARG(1, 2); diff --git a/LUFA/Drivers/USB/HighLevel/Events.h b/LUFA/Drivers/USB/HighLevel/Events.h index 73a804c35..317495cc0 100644 --- a/LUFA/Drivers/USB/HighLevel/Events.h +++ b/LUFA/Drivers/USB/HighLevel/Events.h @@ -36,7 +36,7 @@ * 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 using the EVENT_HANDLER() and HANDLES_EVENT() macros. If an + * Events can be hooked by the user application using the \ref EVENT_HANDLER() and \ref HANDLES_EVENT() macros. If an * event with no associated handler is fired within the library, it by default fires an internal empty stub * function. This is achieved through the use of the GCC compiler's "alias" attribute. * @@ -82,7 +82,7 @@ /** Indicates that a given module can raise a given event. This is the equivalent of putting the * event function's prototype into the module, but in a cleaner way. Each event which may be - * fired via the RAISE_EVENT macro in the module should have an accompanying RAISES_EVENT + * fired via the \ref RAISE_EVENT macro in the module should have an accompanying \ref RAISES_EVENT * prototype in the module's header file. * * Usage Examples: @@ -122,7 +122,7 @@ /** Indicates that a given module handles an event. This is the equivalent of putting the * event function's prototype into the module, but in a cleaner way. Each event which may be - * handled via the EVENT_HANDLER macro in the module should have an accompanying HANDLES_EVENT + * handled via the \ref EVENT_HANDLER macro in the module should have an accompanying \ref HANDLES_EVENT * prototype in the module's header file. * * Usage Examples: @@ -178,7 +178,7 @@ * 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 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. + * and disconnection events may be manually fired by \ref RAISE_EVENT(), and the \ref USB_IsConnected global changed manually. * * \see USBTask.h for more information on the USB management task and reducing CPU usage. */ @@ -196,7 +196,7 @@ * 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 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. + * and disconnection events may be manually fired by \ref RAISE_EVENT(), and the \ref USB_IsConnected global changed manually. * * \see USBTask.h for more information on the USB management task and reducing CPU usage. */ @@ -205,7 +205,7 @@ /** Event for USB device power on failure. This event fires when the USB interface fails to * initialize correctly due to a hardware or software fault. * - * \param ErrorCode Error code indicating the failure reason, a value in USB_PowerOnErrorCodes_t + * \param ErrorCode Error code indicating the failure reason, a value in \ref USB_PowerOnErrorCodes_t * located in LowLevel.h. */ void USB_PowerOnFail(const uint8_t ErrorCode); @@ -224,7 +224,7 @@ /** Event for USB host error. This event fires when a hardware fault has occurred whilst the USB * interface is in host mode. * - * \param ErrorCode Error code indicating the failure reason, a value in USB_Host_ErrorCodes_t + * \param ErrorCode Error code indicating the failure reason, a value in \ref USB_Host_ErrorCodes_t * located in Host.h. * * \note This event only exists on USB AVR models which supports host mode. @@ -236,7 +236,7 @@ /** Event for USB device attachment. This event fires when a the USB interface is in host mode, and * a USB device has been connected to the USB interface. This is interrupt driven, thus fires before - * the standard USB_DeviceConnect event and so can be used to programmatically start the USB management + * the standard \ref USB_Connect event and so can be used to programmatically start the USB management * task to reduce CPU consumption. * * \note This event only exists on USB AVR models which supports host mode. @@ -291,19 +291,13 @@ * issued to the device which must be handled appropriately. Due to the strict timing requirements * on control transfers, interrupts are disabled during control request processing. * - * \param bRequest Request value, indicating what command the host has issued. - * \param bmRequestType Mask indicating the request data direction (if any), type and recipient. - * * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * LowLevel.h documentation). * * \note Requests should be handled in the same manner as described in the USB 2.0 Specification, - * or appropriate class' specification. In all instances, the library has already read the - * request bmRequestType and bRequest values out (into the Request and RequestType parameters - * respectively) so that it can correctly determine if it is able to handle the request - * internally, or hand off the request to the user application via this event. Other request - * parameters (wValue, wIndex, wLength, and Data) remain in the control endpoint bank until - * read out by the user application for processing. + * or appropriate class specification. In all instances, the library has already read the + * request SETUP parameters into the \ref USB_ControlRequest structure which should then be used + * by the application to determine how to handle the issued request. */ void USB_UnhandledControlPacket(void); @@ -311,7 +305,7 @@ * selected configuration number while in device mode. This event should be hooked in device * applications to create the endpoints and configure the device for the selected configuration. * - * This event fires after the value of USB_ConfigurationNumber has been changed. + * This event fires after the value of \ref USB_ConfigurationNumber has been changed. * * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * LowLevel.h documentation). @@ -325,7 +319,7 @@ * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * LowLevel.h documentation). * - * \see USB_WakeUp() event for accompanying Wake Up event. + * \see \ref USB_WakeUp() event for accompanying Wake Up event. */ void USB_Suspend(void); @@ -337,7 +331,7 @@ * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * LowLevel.h documentation). * - * \see USB_Suspend() event for accompanying Suspend event. + * \see \ref USB_Suspend() event for accompanying Suspend event. */ void USB_WakeUp(void); @@ -356,7 +350,7 @@ * and an error occurs which prevents it from operating normally. * * \param ErrorCode Error code indicating the source of the error. One of the values in the - * USB_Device_ErrorCodes_t enum located in Device.h. + * \ref USB_Device_ErrorCodes_t enum located in Device.h. * * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * LowLevel.h documentation). diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index 431080b72..caa0fb046 100644 --- a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h +++ b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h @@ -90,85 +90,85 @@ #define VERSION_BCD(x) ((((VERSION_TENS(x) << 4) | VERSION_ONES(x)) << 8) | \ ((VERSION_TENTHS(x) << 4) | VERSION_HUNDREDTHS(x))) - /** String language ID for the English language. Should be used in USB_Descriptor_Language_t descriptors + /** String language ID for the English language. Should be used in \ref USB_Descriptor_String_t descriptors * to indicate that the English language is supported by the device in its string descriptors. */ #define LANGUAGE_ID_ENG 0x0409 - /** Can be masked with an endpoint address for a USB_Descriptor_Endpoint_t endpoint descriptor's + /** Can be masked with an endpoint address for a \ref USB_Descriptor_Endpoint_t endpoint descriptor's * EndpointAddress value to indicate to the host that the endpoint is of the IN direction (i.e, from * device to host). */ #define ENDPOINT_DESCRIPTOR_DIR_IN 0x80 - /** Can be masked with an endpoint address for a USB_Descriptor_Endpoint_t endpoint descriptor's + /** Can be masked with an endpoint address for a \ref USB_Descriptor_Endpoint_t endpoint descriptor's * EndpointAddress value to indicate to the host that the endpoint is of the OUT direction (i.e, from * host to device). */ #define ENDPOINT_DESCRIPTOR_DIR_OUT 0x00 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t * descriptor's ConfigAttributes value to indicate that the specified configuration can draw its power * from the host's VBUS line. */ #define USB_CONFIG_ATTR_BUSPOWERED 0x80 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t * descriptor's ConfigAttributes value to indicate that the specified configuration can draw its power * from the device's own power source. */ #define USB_CONFIG_ATTR_SELFPOWERED 0xC0 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t * descriptor's ConfigAttributes value to indicate that the specified configuration supports the * remote wakeup feature of the USB standard, allowing a suspended USB device to wake up the host upon * request. */ #define USB_CONFIG_ATTR_REMOTEWAKEUP 0xA0 - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is not synchronized. * * \see The USB specification for more details on the possible Endpoint attributes. */ #define ENDPOINT_ATTR_NO_SYNC (0 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is asynchronous. * * \see The USB specification for more details on the possible Endpoint attributes. */ #define ENDPOINT_ATTR_ASYNC (1 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is adaptive. * * \see The USB specification for more details on the possible Endpoint attributes. */ #define ENDPOINT_ATTR_ADAPTIVE (2 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is synchronized. * * \see The USB specification for more details on the possible Endpoint attributes. */ #define ENDPOINT_ATTR_SYNC (3 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is used for data transfers. * * \see The USB specification for more details on the possible Endpoint usage attributes. */ #define ENDPOINT_USAGE_DATA (0 << 4) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is used for feedback. * * \see The USB specification for more details on the possible Endpoint usage attributes. */ #define ENDPOINT_USAGE_FEEDBACK (1 << 4) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's * Attributes value to indicate that the specified endpoint is used for implicit feedback. * * \see The USB specification for more details on the possible Endpoint usage attributes. @@ -180,7 +180,7 @@ /* Events: */ #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) - /** This module raises the Device Error event while in device mode, if the USB_GetDescriptor() + /** This module raises the Device Error event while in device mode, if the \ref USB_GetDescriptor() * routine is not hooked in the user application to properly return descriptors to the library. * * \see Events.h for more information on this event. @@ -215,7 +215,7 @@ { #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__) uint8_t Size; /**< Size of the descriptor, in bytes. */ - uint8_t Type; /**< Type of the descriptor, either a value in DescriptorTypes_t or a value + uint8_t Type; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value * given by the specific class. */ #else @@ -251,7 +251,7 @@ * host will request this string via a separate * control request for the string descriptor. * - * \note If no string supplied, use NO_DESCRIPTOR. + * \note If no string supplied, use \ref NO_DESCRIPTOR. */ uint8_t ProductStrIndex; /**< String index for the product name/details. * @@ -309,7 +309,7 @@ */ uint8_t MaxPowerConsumption; /**< Maximum power consumption of the device while in the - * current configuration, calculated by the USB_CONFIG_POWER_MA() + * current configuration, calculated by the \ref USB_CONFIG_POWER_MA() * macro. */ #else @@ -364,7 +364,7 @@ #endif } USB_Descriptor_Interface_t; - /** Type define for a standard interface association descriptor. + /** Type define for a standard Interface Association descriptor. * * This descriptor has been added as a supplement to the USB2.0 standard, in the ECN located at * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows compound @@ -442,7 +442,7 @@ } USB_Descriptor_Endpoint_t; /** Type define for a standard string descriptor. Unlike other standard descriptors, the length - * of the descriptor for placement in the descriptor header must be determined by the USB_STRING_LEN() + * of the descriptor for placement in the descriptor header must be determined by the \ref USB_STRING_LEN() * macro rather than by the size of the descriptor structure, as the length is not fixed. * * This structure should also be used for string index 0, which contains the supported language IDs for @@ -479,7 +479,7 @@ /* 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 except for the ATTR_WEAK attribute) so that the library can call it to retrieve descriptor + * prototype and name except for the \ref ATTR_WEAK attribute) so that the library can call it to retrieve descriptor * data. * * \param wValue The type of the descriptor to retrieve in the upper byte, and the index in the @@ -490,7 +490,7 @@ * otherwise zero for standard descriptors, or as defined in a class-specific * standards. * \param DescriptorAddress Pointer to the descriptor in memory. This should be set by the routine to - * the location of the descriptor, found by the DESCRIPTOR_ADDRESS macro. + * the location of the descriptor, found by the \ref DESCRIPTOR_ADDRESS() macro. * * \note By default, the library expects all descriptors to be located in flash memory via the PROGMEM attribute. * If descriptors should be located in RAM or EEPROM instead (to speed up access in the case of RAM, or to @@ -498,7 +498,7 @@ * 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 NO_DESCRIPTOR otherwise + * \return Size in bytes of the descriptor if it exists, zero or \ref NO_DESCRIPTOR otherwise */ uint16_t USB_GetDescriptor(const uint16_t wValue, const uint8_t wIndex, void** const DescriptorAddress) ATTR_WARN_UNUSED_RESULT ATTR_WEAK ATTR_NON_NULL_PTR_ARG(3); diff --git a/LUFA/Drivers/USB/HighLevel/StdRequestType.h b/LUFA/Drivers/USB/HighLevel/StdRequestType.h index 6f214893b..fc626cc0a 100644 --- a/LUFA/Drivers/USB/HighLevel/StdRequestType.h +++ b/LUFA/Drivers/USB/HighLevel/StdRequestType.h @@ -66,58 +66,58 @@ /** Request data direction mask, indicating that the request data will flow from host to device. * - * \see CONTROL_REQTYPE_DIRECTION macro. + * \see \ref CONTROL_REQTYPE_DIRECTION macro. */ #define REQDIR_HOSTTODEVICE (0 << 7) /** Request data direction mask, indicating that the request data will flow from device to host. * - * \see CONTROL_REQTYPE_DIRECTION macro. + * \see \ref CONTROL_REQTYPE_DIRECTION macro. */ #define REQDIR_DEVICETOHOST (1 << 7) /** Request type mask, indicating that the request is a standard request. * - * \see CONTROL_REQTYPE_TYPE macro. + * \see \ref CONTROL_REQTYPE_TYPE macro. */ #define REQTYPE_STANDARD (0 << 5) /** Request type mask, indicating that the request is a class-specific request. * - * \see CONTROL_REQTYPE_TYPE macro. + * \see \ref CONTROL_REQTYPE_TYPE macro. */ #define REQTYPE_CLASS (1 << 5) /** Request type mask, indicating that the request is a vendor specific request. * - * \see CONTROL_REQTYPE_TYPE macro. + * \see \ref CONTROL_REQTYPE_TYPE macro. */ #define REQTYPE_VENDOR (2 << 5) /** Request recipient mask, indicating that the request is to be issued to the device as a whole. * - * \see CONTROL_REQTYPE_RECIPIENT macro. + * \see \ref CONTROL_REQTYPE_RECIPIENT macro. */ #define REQREC_DEVICE (0 << 0) /** Request recipient mask, indicating that the request is to be issued to an interface in the * currently selected configuration. * - * \see CONTROL_REQTYPE_RECIPIENT macro. + * \see \ref CONTROL_REQTYPE_RECIPIENT macro. */ #define REQREC_INTERFACE (1 << 0) /** Request recipient mask, indicating that the request is to be issued to an endpoint in the * currently selected configuration. * - * \see CONTROL_REQTYPE_RECIPIENT macro. + * \see \ref CONTROL_REQTYPE_RECIPIENT macro. */ #define REQREC_ENDPOINT (2 << 0) /** Request recipient mask, indicating that the request is to be issued to an unspecified element * in the currently selected configuration. * - * \see CONTROL_REQTYPE_RECIPIENT macro. + * \see \ref CONTROL_REQTYPE_RECIPIENT macro. */ #define REQREC_OTHER (3 << 0) @@ -151,7 +151,7 @@ /* Enums: */ /** Enumeration for the various standard request commands. These commands are applicable when the - * request type is REQTYPE_STANDARD (with the exception of REQ_GetDescriptor, which is always + * request type is \ref REQTYPE_STANDARD (with the exception of \ref REQ_GetDescriptor, which is always * handled regardless of the request type value). * * \see Chapter 9 of the USB 2.0 Specification. @@ -160,41 +160,41 @@ { REQ_GetStatus = 0, /**< Implemented in the library for device, endpoint and interface * recipients. Passed to the user application for other recipients - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_ClearFeature = 1, /**< Implemented in the library for device, endpoint and interface * recipients. Passed to the user application for other recipients - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_SetFeature = 3, /**< Implemented in the library for device, endpoint and interface * recipients. Passed to the user application for other recipients - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_SetAddress = 5, /**< Implemented in the library for the device recipient. Passed * to the user application for other recipients via the - * USB_UnhandledControlPacket() event when received in + * \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_GetDescriptor = 6, /**< Implemented in the library for all recipients and all request * types. */ REQ_SetDescriptor = 7, /**< Not implemented in the library, passed to the user application - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_GetConfiguration = 8, /**< Implemented in the library for the device recipient. Passed * to the user application for other recipients via the - * USB_UnhandledControlPacket() event when received in + * \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_SetConfiguration = 9, /**< Implemented in the library for the device recipient. Passed * to the user application for other recipients via the - * USB_UnhandledControlPacket() event when received in + * \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_GetInterface = 10, /**< Not implemented in the library, passed to the user application - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_SetInterface = 11, /**< Not implemented in the library, passed to the user application - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ REQ_SynchFrame = 12, /**< Not implemented in the library, passed to the user application - * via the USB_UnhandledControlPacket() event when received in + * via the \ref USB_UnhandledControlPacket() event when received in * device mode. */ }; diff --git a/LUFA/Drivers/USB/HighLevel/StreamCallbacks.h b/LUFA/Drivers/USB/HighLevel/StreamCallbacks.h index 5f0b73742..6a18920c3 100644 --- a/LUFA/Drivers/USB/HighLevel/StreamCallbacks.h +++ b/LUFA/Drivers/USB/HighLevel/StreamCallbacks.h @@ -47,7 +47,7 @@ * these functions are used) which allow the user application to abort the transfer when certain * arbitrary conditions are met. * - * Stream callback functions should return a value from the StreamCallback_Return_ErrorCodes_t + * Stream callback functions should return a value from the \ref StreamCallback_Return_ErrorCodes_t * enum. * * Usage Example (Device Endpoint, but applicable for Host Pipes also): diff --git a/LUFA/Drivers/USB/HighLevel/USBInterrupt.h b/LUFA/Drivers/USB/HighLevel/USBInterrupt.h index c5b0a8358..ee13f2554 100644 --- a/LUFA/Drivers/USB/HighLevel/USBInterrupt.h +++ b/LUFA/Drivers/USB/HighLevel/USBInterrupt.h @@ -70,7 +70,7 @@ /** Disables the given USB interrupt vector. * - * \see USB_INT_Enable() + * \see \ref USB_INT_Enable() */ #define USB_INT_Disable(int) MACROS{ USB_INT_GET_EN_REG(int) &= ~(USB_INT_GET_EN_MASK(int)); }MACROE @@ -96,7 +96,7 @@ * 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 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. + * and disconnection events may be manually fired by \ref RAISE_EVENT(), and the USB_IsConnected global changed manually. */ RAISES_EVENT(USB_Connect); @@ -108,7 +108,7 @@ * 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 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. + * and disconnection events may be manually fired by \ref RAISE_EVENT(), and the USB_IsConnected global changed manually. */ RAISES_EVENT(USB_Disconnect); diff --git a/LUFA/Drivers/USB/HighLevel/USBTask.h b/LUFA/Drivers/USB/HighLevel/USBTask.h index 7e88ce88b..918fa5e31 100644 --- a/LUFA/Drivers/USB/HighLevel/USBTask.h +++ b/LUFA/Drivers/USB/HighLevel/USBTask.h @@ -67,14 +67,14 @@ * 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 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection - * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually. + * and disconnection events may be manually fired by \ref RAISE_EVENT(), and the \ref USB_IsConnected global changed manually. * * \ingroup Group_USBManagement */ extern volatile bool USB_IsConnected; /** Indicates if the USB interface is currently initialized but not necessarily connected to a host - * or device (i.e. if USB_Init() has been run). If this is false, all other library globals are invalid. + * or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals are invalid. * * \note This variable should be treated as read-only in the user application, and never manually * changed in value. @@ -84,8 +84,8 @@ extern volatile bool USB_IsInitialized; /** Structure containing the last received Control request when in Device mode (for use in user-applications - * inside of the USB_UnhandledControlPacket() event, or for filling up with a control request to issue when - * in Host mode before calling USB_Host_SendControlRequest(). + * inside of the \ref USB_UnhandledControlPacket() event, or for filling up with a control request to issue when + * in Host mode before calling \ref USB_Host_SendControlRequest(). * * \ingroup Group_USBManagement */ @@ -94,7 +94,7 @@ #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) /** Indicates if the USB interface is currently suspended by the host when in device mode. When suspended, * the device should consume minimal power, and cannot communicate to the host. If Remote Wakeup is - * supported by the device and USB_RemoteWakeupEnabled is true, suspension can be terminated by the device + * supported by the device and \ref USB_RemoteWakeupEnabled is true, suspension can be terminated by the device * by issuing a Remote Wakeup request. * * \note This global is only present if the user application can be a USB device. @@ -109,11 +109,11 @@ #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) /** Indicates the current host state machine state. When in host mode, this indicates the state - * via one of the values of the USB_Host_States_t enum values in Host.h. + * via one of the values of the \ref USB_Host_States_t enum values in Host.h. * - * This value may be altered by the user application to implement the HOST_STATE_Addressed, - * HOST_STATE_Configured, HOST_STATE_Ready and HOST_STATE_Suspended states which are not implemented - * by the library. + * This value may be altered by the user application to implement the \ref HOST_STATE_Addressed, + * \ref HOST_STATE_Configured, \ref HOST_STATE_Ready and \ref HOST_STATE_Suspended states which + * are not implemented by the library. * * \note This global is only present if the user application can be a USB host. * @@ -124,35 +124,35 @@ /* Throwable Events: */ #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) - /** This module raises the USB Connect event when a USB device has been connected whilst in host + /** This module raises the \ref USB_Connect event when a USB device has been connected whilst in host * mode, but not yet enumerated. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_Connect); - /** This module raises the USB Device Attached event when in host mode, and a device is attached + /** This module raises the \ref USB_DeviceAttached event when in host mode, and a device is attached * to the AVR's USB interface. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_DeviceAttached); - /** This module raises the USB Device Unattached event when in host mode, and a device is removed + /** This module raises the \ref USB_DeviceUnattached event when in host mode, and a device is removed * from the AVR's USB interface. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_DeviceUnattached); - /** This module raises the USB Device Enumeration Failed event when in host mode, and an + /** This module raises the \ref USB_DeviceEnumerationFailed event when in host mode, and an * attached USB device has failed to successfully enumerated. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_DeviceEnumerationFailed); - /** This module raises the USB Device Enumeration Complete event when in host mode, and an + /** This module raises the \ref USB_DeviceEnumerationComplete event when in host mode, and an * attached USB device has been successfully enumerated and ready to be used by the user * application. * @@ -160,7 +160,7 @@ */ RAISES_EVENT(USB_DeviceEnumerationComplete); - /** This module raises the USB Disconnect event when an attached USB device is removed from the USB + /** This module raises the \ref USB_Disconnect event when an attached USB device is removed from the USB * bus. * * \see Events.h for more information on this event. @@ -177,11 +177,11 @@ * The USB task must be serviced within 50mS in all modes, when needed. The task may be serviced * at all times, or (for minimum CPU consumption): * - * - In device mode, it may be disabled at start-up, enabled on the firing of the USB_Connect event - * and disabled again on the firing of the USB_Disconnect event. + * - In device mode, it may be disabled at start-up, enabled on the firing of the \ref USB_Connect event + * and disabled again on the firing of the \ref USB_Disconnect event. * - * - In host mode, it may be disabled at start-up, enabled on the firing of the USB_DeviceAttached - * event and disabled again on the firing of the USB_DeviceUnattached event. + * - In host mode, it may be disabled at start-up, enabled on the firing of the \ref USB_DeviceAttached + * event and disabled again on the firing of the \ref USB_DeviceUnattached event. * * \see Events.h for more information on the USB events. * diff --git a/LUFA/Drivers/USB/LowLevel/DevChapter9.h b/LUFA/Drivers/USB/LowLevel/DevChapter9.h index 10a91937f..b3cac2d50 100644 --- a/LUFA/Drivers/USB/LowLevel/DevChapter9.h +++ b/LUFA/Drivers/USB/LowLevel/DevChapter9.h @@ -83,22 +83,22 @@ extern bool USB_CurrentlySelfPowered; /* Throwable Events: */ - /** This module raises the USB_UnhandledControlPacket event when a request to the default control + /** This module raises the \ref USB_UnhandledControlPacket event when a request to the default control * endpoint has been received, but the library does not implement an internal handler for it. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_UnhandledControlPacket); - /** This module raises the USB_ConfigurationChanged event when the host issues a REQ_SetConfiguration + /** This module raises the \ref USB_ConfigurationChanged event when the host issues a \ref REQ_SetConfiguration * device request, to change the currently selected configuration number. * * \see Events.h for more information on this event. */ RAISES_EVENT(USB_ConfigurationChanged); - /** This module raises the USB_DeviceEnumerationComplete event when the host has completed its - * enumeration of the device (i.e. when a REQ_SetConfiguration request changes the current configuration + /** This module raises the \ref USB_DeviceEnumerationComplete event when the host has completed its + * enumeration of the device (i.e. when a \ref REQ_SetConfiguration request changes the current configuration * number from 0 to a non-zero value). * * \see Events.h for more information on this event. diff --git a/LUFA/Drivers/USB/LowLevel/Device.h b/LUFA/Drivers/USB/LowLevel/Device.h index 206a99361..b3a11d27b 100644 --- a/LUFA/Drivers/USB/LowLevel/Device.h +++ b/LUFA/Drivers/USB/LowLevel/Device.h @@ -51,7 +51,7 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER) || defined(__DOXYGEN__) - /** Mask for the Options parameter of the USB_Init() function. This indicates that the + /** Mask for the Options parameter of the \ref USB_Init() function. This indicates that the * USB interface should be initialized in low speed (1.5Mb/s) mode. * * \note Low Speed mode is not available on all USB AVR models. @@ -78,7 +78,7 @@ * \note This macro should only be used if the device has indicated to the host that it * supports the Remote Wakeup feature in the device descriptors, and should only be * issued if the host is currently allowing remote wakeup events from the device (i.e., - * the USB_RemoteWakeupEnabled flag is set, see DevChapter9.h documentation). + * the \ref USB_RemoteWakeupEnabled flag is set). * * \see StdDescriptors.h for more information on the RMWAKEUP feature and device descriptors. */ @@ -87,7 +87,7 @@ /** Indicates if a Remote Wakeup request is being sent to the host. This returns true if a * remote wakeup is currently being sent, false otherwise. * - * This can be used in conjunction with the USB_Device_IsUSBSuspended() macro to determine if + * This can be used in conjunction with the \ref USB_Device_IsUSBSuspended() macro to determine if * a sent RMWAKEUP request was accepted or rejected by the host. * * \note This macro should only be used if the device has indicated to the host that it @@ -99,9 +99,9 @@ */ static inline bool USB_Device_IsRemoteWakeupSent(void); - /** Indicates if the device is currently suspended by the host. While suspended, the device is - * to enter a low power state until resumed by the host. While suspended no USB traffic to or - * from the device can occur (except for Remote Wakeup requests). + /** Indicates if the device is currently suspended by the host. Whilst suspended, the device is + * to enter a low power state until resumed by the host. No USB traffic to or from the device + * can occur (except for Remote Wakeup requests) during suspension by the host. * * \return Boolean true if the USB communications have been suspended by the host, false otherwise. */ @@ -115,17 +115,17 @@ #endif /* Enums: */ - /** Enum for the ErrorCode parameter of the USB_DeviceError event. + /** Enum for the ErrorCode parameter of the \ref USB_DeviceError event. * * \see Events.h for more information on this event. */ enum USB_Device_ErrorCodes_t { - DEVICE_ERROR_GetDescriptorNotHooked = 0, /**< Indicates that the GetDescriptor() method + DEVICE_ERROR_GetDescriptorNotHooked = 0, /**< Indicates that the \ref USB_GetDescriptor() method * has not been hooked by the user application. * * \see StdDescriptors.h for more information on - * the GetDescriptor() method. + * the \ref USB_GetDescriptor() method. */ }; diff --git a/LUFA/Drivers/USB/LowLevel/Endpoint.h b/LUFA/Drivers/USB/LowLevel/Endpoint.h index 816e7632a..172ab33d7 100644 --- a/LUFA/Drivers/USB/LowLevel/Endpoint.h +++ b/LUFA/Drivers/USB/LowLevel/Endpoint.h @@ -69,24 +69,24 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Endpoint data direction mask for Endpoint_ConfigureEndpoint(). This indicates that the endpoint + /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint * should be initialized in the OUT direction - i.e. data flows from host to device. */ #define ENDPOINT_DIR_OUT (0 << EPDIR) - /** Endpoint data direction mask for Endpoint_ConfigureEndpoint(). This indicates that the endpoint + /** Endpoint data direction mask for \ref Endpoint_ConfigureEndpoint(). This indicates that the endpoint * should be initialized in the IN direction - i.e. data flows from device to host. */ #define ENDPOINT_DIR_IN (1 << EPDIR) - /** Mask for the bank mode selection for the Endpoint_ConfigureEndpoint() macro. This indicates + /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates * that the endpoint should have one single bank, which requires less USB FIFO memory but results * in slower transfers as only one USB device (the AVR or the host) can access the endpoint's * bank at the one time. */ #define ENDPOINT_BANK_SINGLE (0 << EPBK0) - /** Mask for the bank mode selection for the Endpoint_ConfigureEndpoint() macro. This indicates + /** Mask for the bank mode selection for the \ref Endpoint_ConfigureEndpoint() macro. This indicates * that the endpoint should have two banks, which requires more USB FIFO memory but results * in faster transfers as one USB device (the AVR or the host) can access one bank while the other * accesses the second bank. @@ -146,7 +146,7 @@ * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the * endpoint is selected), and will fire the common endpoint interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define ENDPOINT_INT_SETUP UEIENX, (1 << RXSTPE), UEINTX, (1 << RXSTPI) @@ -160,7 +160,7 @@ * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the * endpoint is selected), and will fire the common endpoint interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define ENDPOINT_INT_IN UEIENX, (1 << TXINE) , UEINTX, (1 << TXINI) @@ -174,7 +174,7 @@ * \note This interrupt must be enabled and cleared on *each* endpoint which requires it (after the * endpoint is selected), and will fire the common endpoint interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define ENDPOINT_INT_OUT UEIENX, (1 << RXOUTE), UEINTX, (1 << RXOUTI) @@ -200,7 +200,7 @@ static inline uint8_t Endpoint_GetCurrentEndpoint(void); /** Selects the given endpoint number. If the address from the device descriptors is used, the - * value should be masked with the ENDPOINT_EPNUM_MASK constant to extract only the endpoint + * value should be masked with the \ref ENDPOINT_EPNUM_MASK constant to extract only the endpoint * number (and discarding the endpoint direction bit). * * Any endpoint operations which do not require the endpoint number to be indicated will operate on @@ -220,8 +220,7 @@ /** Enables the currently selected endpoint so that data can be sent and received through it to * and from a host. * - * \note Endpoints must first be configured properly rather than just being enabled via the - * Endpoint_ConfigureEndpoint() macro, which calls Endpoint_EnableEndpoint() automatically. + * \note Endpoints must first be configured properly via \ref Endpoint_ConfigureEndpoint(). */ static inline void Endpoint_EnableEndpoint(void); @@ -330,7 +329,7 @@ * way for devices to indicate invalid commands to the host so that the current transfer can be * aborted and the host can begin its own recovery sequence. * - * The currently selected endpoint remains stalled until either the Endpoint_ClearStall() macro + * The currently selected endpoint remains stalled until either the \ref Endpoint_ClearStall() macro * is called, or the host issues a CLEAR FEATURE request to the device for the currently selected * endpoint. * @@ -415,7 +414,7 @@ #endif /* Enums: */ - /** Enum for the possible error return codes of the Endpoint_WaitUntilReady function. + /** Enum for the possible error return codes of the \ref Endpoint_WaitUntilReady() function. * * \ingroup Group_EndpointRW */ @@ -430,7 +429,7 @@ */ ENDPOINT_READYWAIT_Timeout = 3, /**< The host failed to accept or send the next packet * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. + * \ref USB_STREAM_TIMEOUT_MS macro. */ }; @@ -449,7 +448,7 @@ */ ENDPOINT_RWSTREAM_ERROR_Timeout = 2, /**< The host failed to accept or send the next packet * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. + * \ref USB_STREAM_TIMEOUT_MS macro. */ ENDPOINT_RWSTREAM_ERROR_CallbackAborted = 3, /**< Indicates that the stream's callback function * aborted the transfer early. @@ -703,15 +702,15 @@ * device (i.e. endpoint 1 should be configured before endpoint 2 and so on). * * The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction - * may be either ENDPOINT_DIR_OUT or ENDPOINT_DIR_IN. + * may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN. * * The bank size must indicate the maximum packet size that the endpoint can handle. Different * endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's * datasheet to determine the maximum bank size for each endpoint. * - * The banking mode may be either ENDPOINT_BANK_SINGLE or ENDPOINT_BANK_DOUBLE. + * The banking mode may be either \ref ENDPOINT_BANK_SINGLE or \ref ENDPOINT_BANK_DOUBLE. * - * The success of this routine can be determined via the Endpoint_IsConfigured() macro. + * The success of this routine can be determined via the \ref Endpoint_IsConfigured() macro. * * By default, the routine is entirely dynamic, and will accept both constant and variable inputs. * If dynamic configuration is unused, a small space savings can be made by defining the @@ -733,18 +732,18 @@ * * \ingroup Group_EndpointRW * - * \return A value from the Endpoint_WaitUntilReady_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum. */ uint8_t Endpoint_WaitUntilReady(void); /** Reads and discards the given number of bytes from the endpoint from the given buffer, * discarding fully read packets from the host as needed. The last packet is not automatically * discarded once the remaining bytes has been read; the user is responsible for manually - * discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between + * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between * each USB packet, the given stream callback function is executed repeatedly until the next * packet is ready, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -755,7 +754,7 @@ * \param Length Number of bytes to send via the currently selected endpoint. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Discard_Stream(uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -766,11 +765,11 @@ /** Writes the given number of bytes to the endpoint from the given buffer in little endian, * sending full packets to the host as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function + * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early * aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -782,7 +781,7 @@ * \param Length Number of bytes to read for the currently selected endpoint into the buffer. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Write_Stream_LE(const void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -793,11 +792,11 @@ /** Writes the given number of bytes to the endpoint from the given buffer in big endian, * sending full packets to the host as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function + * \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function * is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early * aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -809,7 +808,7 @@ * \param Length Number of bytes to read for the currently selected endpoint into the buffer. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Write_Stream_BE(const void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -820,11 +819,11 @@ /** Reads the given number of bytes from the endpoint from the given buffer in little endian, * discarding fully read packets from the host as needed. The last packet is not automatically * discarded once the remaining bytes has been read; the user is responsible for manually - * discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between + * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between * each USB packet, the given stream callback function is executed repeatedly until the endpoint * is ready to accept the next packet, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -836,7 +835,7 @@ * \param Length Number of bytes to send via the currently selected endpoint. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -847,11 +846,11 @@ /** Reads the given number of bytes from the endpoint from the given buffer in big endian, * discarding fully read packets from the host as needed. The last packet is not automatically * discarded once the remaining bytes has been read; the user is responsible for manually - * discarding the last packet from the host via the Endpoint_ClearOUT() macro. Between + * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between * each USB packet, the given stream callback function is executed repeatedly until the endpoint * is ready to accept the next packet, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -863,7 +862,7 @@ * \param Length Number of bytes to send via the currently selected endpoint. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Endpoint_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -874,7 +873,7 @@ /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian, * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared * in both failure and success states; the user is responsible for manually clearing the setup OUT to - * finalize the transfer via the Endpoint_ClearOUT() macro. + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. * * \note This routine should only be used on CONTROL type endpoints. * @@ -886,14 +885,14 @@ * \param Buffer Pointer to the source data buffer to read from. * \param Length Number of bytes to read for the currently selected endpoint into the buffer. * - * \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian, * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared * in both failure and success states; the user is responsible for manually clearing the setup OUT to - * finalize the transfer via the Endpoint_ClearOUT() macro. + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. * * \note This routine should only be used on CONTROL type endpoints. * @@ -905,14 +904,14 @@ * \param Buffer Pointer to the source data buffer to read from. * \param Length Number of bytes to read for the currently selected endpoint into the buffer. * - * \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian, * discarding fully read packets from the host as needed. The device IN acknowledgement is not * automatically sent after success or failure states; the user is responsible for manually sending the - * setup IN to finalize the transfer via the Endpoint_ClearIN() macro. + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. * * \note This routine should only be used on CONTROL type endpoints. * @@ -924,14 +923,14 @@ * \param Buffer Pointer to the destination data buffer to write to. * \param Length Number of bytes to send via the currently selected endpoint. * - * \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian, * discarding fully read packets from the host as needed. The device IN acknowledgement is not * automatically sent after success or failure states; the user is responsible for manually sending the - * setup IN to finalize the transfer via the Endpoint_ClearIN() macro. + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. * * \note This routine should only be used on CONTROL type endpoints. * @@ -943,7 +942,7 @@ * \param Buffer Pointer to the destination data buffer to write to. * \param Length Number of bytes to send via the currently selected endpoint. * - * \return A value from the Endpoint_ControlStream_RW_ErrorCodes_t enum. + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); diff --git a/LUFA/Drivers/USB/LowLevel/Host.h b/LUFA/Drivers/USB/LowLevel/Host.h index 62921e866..0eb484374 100644 --- a/LUFA/Drivers/USB/LowLevel/Host.h +++ b/LUFA/Drivers/USB/LowLevel/Host.h @@ -68,7 +68,7 @@ * library will return a timeout error code. * * This value may be overridden in the user project makefile as the value of the - * USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch. + * \ref USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch. */ #define USB_HOST_TIMEOUT_MS 1000 #endif @@ -95,7 +95,7 @@ */ static inline void USB_Host_ResetBus(void); - /** Determines if a previously issued bus reset (via the USB_Host_ResetBus() macro) has + /** Determines if a previously issued bus reset (via the \ref USB_Host_ResetBus() macro) has * completed. * * \return Boolean true if no bus reset is currently being sent, false otherwise. @@ -114,7 +114,7 @@ */ static inline void USB_Host_SuspendBus(void); - /** Determines if the USB bus has been suspended via the use of the USB_Host_SuspendBus() macro, + /** Determines if the USB bus has been suspended via the use of the \ref USB_Host_SuspendBus() macro, * false otherwise. While suspended, no USB communications can occur until the bus is resumed, * except for the Remote Wakeup event from the device if supported. * @@ -200,28 +200,28 @@ HOST_STATE_Suspended = 13, /**< May be implemented by the user project. */ }; - /** Enum for the error codes for the USB_HostError event. + /** Enum for the error codes for the \ref USB_HostError event. * * \see Events.h for more information on this event. */ enum USB_Host_ErrorCodes_t { HOST_ERROR_VBusVoltageDip = 0, /**< VBUS voltage dipped to an unacceptable level. This - * error may be the result of an attached device drawing + * error may be the result of an attached device drawing * too much current from the VBUS line, or due to the * AVR's power source being unable to supply sufficient * current. */ }; - /** Enum for the error codes for the USB_DeviceEnumerationFailed event. + /** Enum for the error codes for the \ref USB_DeviceEnumerationFailed event. * * \see Events.h for more information on this event. */ enum USB_Host_EnumerationErrorCodes_t { HOST_ENUMERROR_NoError = 0, /**< No error occurred. Used internally, this is not a valid - * ErrorCode parameter value for the USB_DeviceEnumerationFailed + * ErrorCode parameter value for the \ref USB_DeviceEnumerationFailed * event. */ HOST_ENUMERROR_WaitStage = 1, /**< One of the delays between enumeration steps failed diff --git a/LUFA/Drivers/USB/LowLevel/HostChapter9.h b/LUFA/Drivers/USB/LowLevel/HostChapter9.h index cbb5ba5a8..1e3f7b258 100644 --- a/LUFA/Drivers/USB/LowLevel/HostChapter9.h +++ b/LUFA/Drivers/USB/LowLevel/HostChapter9.h @@ -46,7 +46,7 @@ /* Public Interface - May be used in end-application: */ /* Enums: */ - /** Enum for the USB_Host_SendControlRequest() return code, indicating the reason for the error + /** Enum for the \ref USB_Host_SendControlRequest() return code, indicating the reason for the error * if the transfer of the request is unsuccessful. * * \ingroup Group_PipeControlReq @@ -65,7 +65,7 @@ }; /* Function Prototypes: */ - /** Sends the request stored in the USB_ControlRequest global structure to the attached device, + /** Sends the request stored in the \ref USB_ControlRequest global structure to the attached device, * and transfers the data stored in the buffer to the device, or from the device to the buffer * as requested. The transfer is made on the currently selected pipe. * @@ -74,7 +74,7 @@ * \param BufferPtr Pointer to the start of the data buffer if the request has a data stage, or * NULL if the request transfers no data to or from the device. * - * \return A value from the USB_Host_SendControlErrorCodes_t enum to indicate the result. + * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_SendControlRequest(void* BufferPtr); diff --git a/LUFA/Drivers/USB/LowLevel/LowLevel.h b/LUFA/Drivers/USB/LowLevel/LowLevel.h index 5c474df70..3bf413745 100644 --- a/LUFA/Drivers/USB/LowLevel/LowLevel.h +++ b/LUFA/Drivers/USB/LowLevel/LowLevel.h @@ -102,18 +102,18 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Mode mask for the USB_CurrentMode global. This indicates that the USB interface is currently not + /** Mode mask for the \ref USB_CurrentMode global. This indicates that the USB interface is currently not * initialized into any mode. */ #define USB_MODE_NONE 0 - /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the + /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the * USB interface is or should be initialized in the USB device mode. */ #define USB_MODE_DEVICE 1 #if defined(USB_CAN_BE_HOST) || defined(__DOXYGEN__) - /** Mode mask for the USB_CurrentMode global and the USB_Init() function. This indicates that the + /** Mode mask for the \ref USB_CurrentMode global and the \ref USB_Init() function. This indicates that the * USB interface is or should be initialized in the USB host mode. * * \note This token is not available on AVR models which do not support host mode. @@ -122,7 +122,7 @@ #endif #if defined(USB_CAN_BE_BOTH) || defined(__DOXYGEN__) - /** Mode mask for the the USB_Init() function. This indicates that the USB interface should be + /** Mode mask for the the \ref USB_Init() function. This indicates that the USB interface should be * initialized into whatever mode the UID pin of the USB AVR indicates, and that the device * should swap over its mode when the level of the UID pin changes during operation. * @@ -131,27 +131,27 @@ #define USB_MODE_UID 3 #endif - /** Regulator disable option mask for USB_Init(). This indicates that the internal 3.3V USB data pad + /** Regulator disable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad * regulator should be enabled to regulate the data pin voltages to within the USB standard. * * \note See USB AVR data sheet for more information on the internal pad regulator. */ #define USB_OPT_REG_DISABLED (1 << 1) - /** Regulator enable option mask for USB_Init(). This indicates that the internal 3.3V USB data pad + /** Regulator enable option mask for \ref USB_Init(). This indicates that the internal 3.3V USB data pad * regulator should be disabled and the AVR's VCC level used for the data pads. * * \note See USB AVR data sheet for more information on the internal pad regulator. */ #define USB_OPT_REG_ENABLED (0 << 1) - /** Manual PLL control option mask for USB_Init(). This indicates to the library that the user application + /** Manual PLL control option mask for \ref USB_Init(). This indicates to the library that the user application * will take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock * that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations. */ #define USB_OPT_MANUAL_PLL (1 << 2) - /** Automatic PLL control option mask for USB_Init(). This indicates to the library that the library should + /** Automatic PLL control option mask for \ref USB_Init(). This indicates to the library that the library should * take full responsibility for controlling the AVR's PLL (used to generate the high frequency clock * that the USB controller requires) and ensuring that it is locked at the correct frequency for USB operations. */ @@ -192,7 +192,7 @@ /** Detaches the device from the USB bus. This has the effect of removing the device from any * host if, ceasing USB communications. If no host is present, this prevents any host from - * enumerating the device once attached until USB_Attach() is called. + * enumerating the device once attached until \ref USB_Attach() is called. */ #define USB_Detach() MACROS{ UDCON |= (1 << DETACH); }MACROE @@ -212,7 +212,7 @@ * is not received or acknowledged within this time period, the stream function will fail. * * This value may be overridden in the user project makefile as the value of the - * USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch. + * \ref USB_STREAM_TIMEOUT_MS token, and passed to the compiler using the -D switch. */ #define USB_STREAM_TIMEOUT_MS 100 #endif @@ -229,7 +229,7 @@ * interface reset and re-enumeration. * * \param Mode This is a mask indicating what mode the USB interface is to be initialized to. - * Valid mode masks are USB_MODE_DEVICE, USB_MODE_HOST or USB_MODE_UID. + * Valid mode masks are \ref USB_MODE_DEVICE, \ref USB_MODE_HOST or \ref USB_MODE_UID. * * \param Options Mask indicating the options which should be used when initializing the USB * interface to control the USB interface's behaviour. This should be comprised of @@ -272,7 +272,7 @@ /** Shuts down the USB interface. This turns off the USB interface after deallocating all USB FIFO * memory, endpoints and pipes. When turned off, no USB functionality can be used until the interface - * is restarted with the USB_Init() function. + * is restarted with the \ref USB_Init() function. */ void USB_ShutDown(void); @@ -283,11 +283,11 @@ /* Enums: */ /** Enum for error codes relating to the powering on of the USB interface. These error codes are - * used in the ErrorCode parameter value of the USB_PowerOnFail event. + * used in the ErrorCode parameter value of the \ref USB_PowerOnFail event. */ enum USB_PowerOnErrorCodes_t { - POWERON_ERROR_NoUSBModeSpecified = 0, /**< Indicates that USB_Init() was called with an + POWERON_ERROR_NoUSBModeSpecified = 0, /**< Indicates that \ref USB_Init() was called with an * invalid or missing Mode parameter. */ }; @@ -305,7 +305,7 @@ #if !defined(USE_STATIC_OPTIONS) || defined(__DOXYGEN__) extern volatile uint8_t USB_Options; - /** Indicates the current USB options that the USB interface was initialized with when USB_Init() + /** Indicates the current USB options that the USB interface was initialized with when \ref USB_Init() * was called. This value will be one of the USB_MODE_* masks defined elsewhere in this module. * * \note This variable should be treated as read-only in the user application, and never manually @@ -314,7 +314,7 @@ #endif /* Throwable Events: */ - /** This module raises the USB_Disconnect event if the USB interface is reset (such as during a mode + /** This module raises the \ref USB_Disconnect event if the USB interface is reset (such as during a mode * change while in UID mode) while the USB interface is connected to a device when in host mode, or * a host while in device mode. * diff --git a/LUFA/Drivers/USB/LowLevel/OTG.h b/LUFA/Drivers/USB/LowLevel/OTG.h index 1f59e0cfa..8defff7ff 100644 --- a/LUFA/Drivers/USB/LowLevel/OTG.h +++ b/LUFA/Drivers/USB/LowLevel/OTG.h @@ -102,7 +102,7 @@ * There are two different methods of sending a SRP - either pulses on the VBUS line, or by * pulsing the Data + line via the internal pull-up resistor. * - * \param SRPTypeMask Mask indicating the type of SRP to use, either USB_OTG_SRP_VBUS or USB_OTG_STP_DATA. + * \param SRPTypeMask Mask indicating the type of SRP to use, either \ref USB_OTG_SRP_VBUS or \ref USB_OTG_STP_DATA. */ static inline void USB_OTG_DEV_Initiate_SRP(uint8_t SRPTypeMask); #else @@ -115,7 +115,7 @@ #define USB_OTG_HOST_Accept_HNP() MACROS{ OTGCON |= (1 << HNPREQ); }MACROE - #define USB_OTG_HOST_Reject_HNP() MACROS{ OTGCON &= ~(1 << HNPREQ); }MACROE + #define USB_OTG_HOST_Reject_HNP() MACROS{ OTGCON &= ~(1 << HNPREQ); }MACROE #define USB_OTG_HOST_IsHNPReceived() ((OTGCON & (1 << HNPREQ)) ? true : false) diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 25121cafa..748dc590b 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -77,43 +77,43 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Mask for Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ #define PIPE_ERRORFLAG_CRC16 (1 << 4) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */ + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */ #define PIPE_ERRORFLAG_TIMEOUT (1 << 3) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */ + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */ #define PIPE_ERRORFLAG_PID (1 << 2) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */ + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */ #define PIPE_ERRORFLAG_DATAPID (1 << 1) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */ + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */ #define PIPE_ERRORFLAG_DATATGL (1 << 0) - /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes), + /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes), * which will trigger a control request on the attached device when data is written to the pipe. */ #define PIPE_TOKEN_SETUP (0 << PTOKEN0) - /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes), + /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes), * indicating that the pipe data will flow from device to host. */ #define PIPE_TOKEN_IN (1 << PTOKEN0) - /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes), + /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes), * indicating that the pipe data will flow from host to device. */ #define PIPE_TOKEN_OUT (2 << PTOKEN0) - /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe + /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe * should have one single bank, which requires less USB FIFO memory but results in slower transfers as * only one USB device (the AVR or the attached device) can access the pipe's bank at the one time. */ #define PIPE_BANK_SINGLE (0 << EPBK0) - /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe + /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe * should have two banks, which requires more USB FIFO memory but results in faster transfers as one * USB device (the AVR or the attached device) can access one bank while the other accesses the second * bank. @@ -168,7 +168,7 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define PIPE_INT_IN UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI) @@ -182,7 +182,7 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define PIPE_INT_OUT UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI) @@ -195,7 +195,7 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define PIPE_INT_SETUP UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI) @@ -208,9 +208,9 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. * - * \see Pipe_GetErrorFlags() for more information on the pipe errors. + * \see \ref Pipe_GetErrorFlags() for more information on the pipe errors. */ #define PIPE_INT_ERROR UPIENX, (1 << PERRE), UPINTX, (1 << PERRI) @@ -223,9 +223,9 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. * - * \see Pipe_IsNAKReceived() for more information on pipe NAKs. + * \see \ref Pipe_IsNAKReceived() for more information on pipe NAKs. */ #define PIPE_INT_NAK UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI) @@ -238,7 +238,7 @@ * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe * is selected), and will fire the common pipe interrupt vector. * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. + * \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ #define PIPE_INT_STALL UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI) @@ -278,8 +278,7 @@ /** Enables the currently selected pipe so that data can be sent and received through it to and from * an attached device. * - * \note Pipes must first be configured properly rather than just being enabled via the - * Pipe_ConfigurePipe() macro, which calls Pipe_EnablePipe() automatically. + * \note Pipes must first be configured properly via \ref Pipe_ConfigurePipe(). */ static inline void Pipe_EnablePipe(void); @@ -365,7 +364,7 @@ /** Determines if the master pipe error flag is set for the currently selected pipe, indicating that * some sort of hardware error has occurred on the pipe. * - * \see Pipe_GetErrorFlags() macro for information on retrieving the exact error flag. + * \see \ref Pipe_GetErrorFlags() macro for information on retrieving the exact error flag. * * \return Boolean true if an error has occurred on the selected pipe, false otherwise */ @@ -445,7 +444,7 @@ /** Determines if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on * the currently selected pipe. This occurs when the host sends a packet to the device, but the device * is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been - * received, it must be cleared using Pipe_ClearNAKReceived() before the previous (or any other) packet + * received, it must be cleared using \ref Pipe_ClearNAKReceived() before the previous (or any other) packet * can be re-sent. * * \ingroup Group_PipePacketManagement @@ -458,7 +457,7 @@ * * \ingroup Group_PipePacketManagement * - * \see Pipe_IsNAKReceived() for more details. + * \see \ref Pipe_IsNAKReceived() for more details. */ static inline void Pipe_ClearNAKReceived(void); @@ -559,7 +558,7 @@ PIPE_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while waiting. */ PIPE_READYWAIT_Timeout = 3, /**< The device failed to accept or send the next packet * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. + * \ref USB_STREAM_TIMEOUT_MS macro. */ }; @@ -576,7 +575,7 @@ */ PIPE_RWSTREAM_ERROR_Timeout = 3, /**< The device failed to accept or send the next packet * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. + * \ref USB_STREAM_TIMEOUT_MS macro. */ PIPE_RWSTREAM_ERROR_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted * the transfer early. @@ -811,9 +810,9 @@ * numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to * determine the maximum bank size for each pipe. * - * The banking mode may be either PIPE_BANK_SINGLE or PIPE_BANK_DOUBLE. + * The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE. * - * A newly configured pipe is frozen by default, and must be unfrozen before use via the Pipe_Unfreeze() macro. + * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() macro. * * \note This routine will select the specified pipe, and the pipe will remain selected once the * routine completes regardless of if the pipe configuration succeeds. @@ -835,10 +834,10 @@ /** Writes the given number of bytes to the pipe from the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is + * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -848,7 +847,7 @@ * \param Length Number of bytes to read for the currently selected pipe into the buffer. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -859,10 +858,10 @@ /** Writes the given number of bytes to the pipe from the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is + * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -872,7 +871,7 @@ * \param Length Number of bytes to read for the currently selected pipe into the buffer. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -882,11 +881,11 @@ /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the - * user is responsible for manually discarding the last packet from the device via the Pipe_ClearIN() macro. + * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro. * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, * allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -895,7 +894,7 @@ * \param Length Number of bytes to send via the currently selected pipe. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t Pipe_Discard_Stream(uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -906,10 +905,10 @@ /** Reads the given number of bytes from the pipe into the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is + * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -919,7 +918,7 @@ * \param Length Number of bytes to read for the currently selected pipe to read from. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) @@ -930,10 +929,10 @@ /** Reads the given number of bytes from the pipe into the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is + * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. * - * The callback routine should be created using the STREAM_CALLBACK() macro. If the token + * The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled * and this function has the Callback parameter omitted. * @@ -943,7 +942,7 @@ * \param Length Number of bytes to read for the currently selected pipe to read from. * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) -- cgit v1.2.3