/** Convenience macro to determine the larger of two values.
*
- * \note This macro should only be used with operands that do not have side effects from being evaluated
- * multiple times.
+ * \attention This macro should only be used with operands that do not have side effects from being evaluated
+ * multiple times.
*
* \param[in] x First value to compare
* \param[in] y First value to compare
/** Convenience macro to determine the smaller of two values.
*
- * \note This macro should only be used with operands that do not have side effects from being evaluated
- * multiple times.
+ * \attention This macro should only be used with operands that do not have side effects from being evaluated
+ * multiple times.
*
* \param[in] x First value to compare
* \param[in] y First value to compare
* If enabled, this will indicate that the USB target VBUS line polarity is inverted; i.e. it should be pulled low to enable VBUS to the
* target, and pulled high to stop the target VBUS generation.
*
- * \note On AVR8 architecture devices, this compile time option requires \c NO_AUTO_VBUS_MANAGEMENT to be set.
+ * \attention On AVR8 architecture devices, this compile time option requires \c NO_AUTO_VBUS_MANAGEMENT to be set.
*
* - <b>NO_AUTO_VBUS_MANAGEMENT</b> - (\ref Group_Host) - <i>All Architectures</i> \n
* Disables the automatic management of VBUS to the target, i.e. automatic shut down in the even of an overcurrent situation. When enabled, VBUS
* - PSGroove, a Playstation 3 Homebrew dongle: http://github.com/psgroove
* - PS/2 to USB adapter: https://github.com/makestuff/p2ukbd
* - Reprap with LUFA, a LUFA powered 3D printer: http://code.google.com/p/at90usb1287-code-for-arduino-and-eclipse/
+ * - RFPirate, a RF experimentation platform: https://github.com/ebuller/RF-Pirate
* - RF Transciever using the MRF49XA: http://alternet.us.com/?page_id=1494
* - SD Card reader: http://elasticsheep.com/2010/04/teensy2-usb-mass-storage-with-an-sd-card/
* - SDR1, a Software Defined Radio firmware: https://code.google.com/p/sdr-mk1/
/** Inserts an element into the ring buffer.
*
- * \note Only one execution thread (main program thread or an ISR) may insert into a single buffer
- * otherwise data corruption may occur. Insertion and removal may occur from different execution
- * threads.
+ * \warning Only one execution thread (main program thread or an ISR) may insert into a single buffer
+ * otherwise data corruption may occur. Insertion and removal may occur from different execution
+ * threads.
*
* \param[in,out] Buffer Pointer to a ring buffer structure to insert into.
* \param[in] Data Data element to insert into the buffer.
/** Removes an element from the ring buffer.
*
- * \note Only one execution thread (main program thread or an ISR) may remove from a single buffer
- * otherwise data corruption may occur. Insertion and removal may occur from different execution
- * threads.
+ * \warning Only one execution thread (main program thread or an ISR) may remove from a single buffer
+ * otherwise data corruption may occur. Insertion and removal may occur from different execution
+ * threads.
*
* \param[in,out] Buffer Pointer to a ring buffer structure to retrieve from.
*
/** Retrieves the ADC MUX mask for the given ADC channel number.
*
- * \note This macro will only work correctly on channel numbers that are compile-time
- * constants defined by the preprocessor.
+ * \attention This macro will only work correctly on channel numbers that are compile-time
+ * constants defined by the preprocessor.
*
* \param[in] Channel Index of the ADC channel whose MUX mask is to be retrieved.
*/
*
* \note This must only be called for ADC channels with are connected to a physical port
* pin of the AVR, denoted by its special alternative function ADCx.
- * \n\n
*
- * \note The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
+ * \warning The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
*
* \param[in] ChannelIndex ADC channel number to set up for conversions.
*/
*
* \note This must only be called for ADC channels with are connected to a physical port
* pin of the AVR, denoted by its special alternative function ADCx.
- * \n\n
*
- * \note The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
+ * \warning The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
*
* \param[in] ChannelIndex ADC channel number to set up for conversions.
*/
*
* The generated SCL frequency will be according to the formula <pre>F_CPU / (16 + 2 * BitLength + 4 ^ Prescale)</pre>.
*
- * \note The value of the \c BitLength parameter should not be set below 10 or invalid bus conditions may
- * occur, as indicated in the AVR8 microcontroller datasheet.
+ * \attention The value of the \c BitLength parameter should not be set below 10 or invalid bus conditions may
+ * occur, as indicated in the AVR8 microcontroller datasheet.
*
* \param[in] Prescale Prescaler to use when determining the bus frequency, a \c TWI_BIT_PRESCALE_* value.
* \param[in] BitLength Length of the bits sent on the bus.
* about the number of channels, the sample resolution, acceptable sample frequencies and encoding method used
* in the device's audio streams. See the USB Audio specification for more details.
*
- * \note This descriptor <b>must</b> be followed by one or more \ref USB_Audio_SampleFreq_t elements containing
- * the continuous or discrete sample frequencies.
+ * \attention This descriptor <b>must</b> be followed by one or more \ref USB_Audio_SampleFreq_t elements containing
+ * the continuous or discrete sample frequencies.
*
* \see \ref USB_Audio_StdDescriptor_Format_t for the version of this type with standard element names.
*
* about the number of channels, the sample resolution, acceptable sample frequencies and encoding method used
* in the device's audio streams. See the USB Audio specification for more details.
*
- * \note This descriptor <b>must</b> be followed by one or more 24-bit integer elements containing the continuous
- * or discrete sample frequencies.
+ * \attention This descriptor <b>must</b> be followed by one or more 24-bit integer elements containing the continuous
+ * or discrete sample frequencies.
*
* \see \ref USB_Audio_Descriptor_Format_t for the version of this type with non-standard LUFA specific
* element names.
*
* One major issue with CDC-ACM is that it requires two Interface descriptors,
* which will upset most hosts when part of a multi-function "Composite" USB
- * device, as each interface will be loaded into a separate driver instance. To
- * combat this, you should use the "Interface Association Descriptor" addendum to
- * the USB standard which is available on most OSes when creating Composite devices.
+ * device. This is because each interface will be loaded into a separate driver
+ * instance, causing the two interfaces be become unlinked. To prevent this, you
+ * should use the "Interface Association Descriptor" addendum to the USB 2.0 standard
+ * which is available on most OSes when creating Composite devices.
*
* Another major oversight is that there is no mechanism for the host to notify the
* device that there is a data sink on the host side ready to accept data. This
* means that the device may try to send data while the host isn't listening, causing
- * lengthy blocking timeouts in the transmission routines. To combat this, it is
- * recommended that the virtual serial line DTR (Data Terminal Ready) be used where
- * possible to determine if a host application is ready for data.
+ * lengthy blocking timeouts in the transmission routines. It is thus highly recommended
+ * that the virtual serial line DTR (Data Terminal Ready) signal be used where possible
+ * to determine if a host application is ready for data.
*
* @{
*/
* be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
* line buffering.
*
- * \note The created stream can be given as stdout if desired to direct the standard output from all <stdio.h> functions
+ * \note The created stream can be given as \c stdout if desired to direct the standard output from all <stdio.h> functions
* to the given CDC interface.
* \n\n
*
* be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own\r
* line buffering.\r
*\r
- * \note The created stream can be given as stdout if desired to direct the standard output from all \c <stdio.h> functions\r
+ * \note The created stream can be given as \c stdout if desired to direct the standard output from all \c <stdio.h> functions\r
* to the given AOA interface.\r
* \n\n\r
*\r
* be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
* line buffering.
*
- * \note The created stream can be given as stdout if desired to direct the standard output from all \c <stdio.h> functions
+ * \note The created stream can be given as \c stdout if desired to direct the standard output from all \c <stdio.h> functions
* to the given CDC interface.
* \n\n
*
* device. This should be called once after the stack has enumerated the attached device, while the host state
* machine is in the Addressed state.
*
- * \note Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call
- * to either the \ref HID_Host_SetBootProtocol() or \ref HID_Host_SetReportProtocol() function.
+ * \attention Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call
+ * to either the \ref HID_Host_SetBootProtocol() or \ref HID_Host_SetReportProtocol() function.
*
* \param[in,out] HIDInterfaceInfo Pointer to a structure containing a HID Class host configuration and state.
* \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor.
* \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
* call will fail.
*
- * \note The destination buffer should be large enough to accommodate the largest report that the attached device
- * can generate.
+ * \attention The destination buffer should be large enough to accommodate the largest report that the attached device
+ * can generate.
*
* \param[in,out] HIDInterfaceInfo Pointer to a structure containing a HID Class host configuration and state.
* \param[in] Buffer Buffer to store the received report into.
/** Switches the attached HID device's reporting protocol over to the standard Report protocol mode. This also retrieves
* and parses the device's HID report descriptor, so that the size of each report can be determined in advance.
*
- * \note Whether this function is used or not, the \ref CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID
- * Report Parser this function references <b>must</b> be implemented in the user code.
- * \n\n
+ * \attention Whether this function is used or not, the \ref CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID
+ * Report Parser this function references <b>must</b> be implemented in the user code.
*
* \note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
*
* \n
*
* \note Restrictions apply on the number, size and type of endpoints which can be used
- * when running in low speed mode - refer to the USB 2.0 specification.
+ * when running in low speed mode - please refer to the USB 2.0 specification.
*/
#define USB_DEVICE_OPT_LOWSPEED (1 << 0)
#endif
* Typically, this is implemented so that HID devices (mice, keyboards, etc.) can wake up the
* host computer when the host has suspended all USB devices to enter a low power state.
*
- * \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 \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
- * compile time option is used, this macro is unavailable.
- * \n\n
+ * \attention This function 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 \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
+ * compile time option is used, this function is unavailable.
+ * \n\n
*
- * \note The USB clock must be running for this function to operate. If the stack is initialized with
- * the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
- * before attempting to call this function.
+ * \attention The USB clock must be running for this function to operate. If the stack is initialized with
+ * the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
+ * before attempting to call this function.
*
* \see \ref Group_StdDescriptors for more information on the RMWAKEUP feature and device descriptors.
*/
* \ref EVENT_USB_Device_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when enumerated in device mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_EnableSOFEvents(void)
/** Disables the device mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Device_StartOfFrame() event when enumerated in device mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_DisableSOFEvents(void)
/** Retrieves the maximum bank size in bytes of a given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
/** Retrieves the total number of banks supported by the given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
* More banks uses more USB DPRAM, but offers better performance. Isochronous type
* endpoints <b>must</b> have at least two banks.
*
- * \note When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
- * ascending order, or bank corruption will occur.
- * \n\n
+ * \attention When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
+ * ascending order, or bank corruption will occur.
*
- * \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
- * the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
+ * \note Different endpoints may have different maximum packet sizes based on the endpoint's index - please
+ * refer to the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
* \n\n
*
* \note The default control endpoint should not be manually configured by the user application, as
/** Indicates the number of bytes currently stored in the current endpoint's selected bank.
*
- * \note The return width of this function may differ, depending on the maximum endpoint bank size
- * of the selected AVR model.
- *
* \ingroup Group_EndpointRW_AVR8
*
* \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
* \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
* be used in the device descriptors to ensure this.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
#if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
extern uint8_t USB_Device_ControlEndpointSize;
/** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
* with respect to the data direction. This is a convenience function which can be used to
* simplify user control request handling.
+ *
+ * \note This routine should not be called on non CONTROL type endpoints.
*/
void Endpoint_ClearStatusStage(void);
* \ref EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when a device is enumerated while in host mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_EnableSOFEvents(void)
/** Disables the host mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.
*
- * \note Not available when the NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_DisableSOFEvents(void)
* device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame
* messages to the device.
*
- * \note While the USB bus is suspended, all USB interrupt sources are also disabled; this means that
- * some events (such as device disconnections) will not fire until the bus is resumed.
+ * \attention While the USB bus is suspended, all USB interrupt sources are also disabled; this means that
+ * some events (such as device disconnections) will not fire until the bus is resumed.
*/
static inline void USB_Host_SuspendBus(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_SuspendBus(void)
/* Inline Functions: */
/** Indicates the number of bytes currently stored in the current pipes's selected bank.
*
- * \note The return width of this function may differ, depending on the maximum pipe bank size
- * of the selected AVR model.
- *
* \ingroup Group_PipeRW_AVR8
*
* \return Total number of bytes in the currently selected pipe's FIFO buffer.
* descriptor once the USB interface is initialized into host mode and a device is attached
* to the USB bus.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
extern uint8_t USB_Host_ControlPipeSize;
* uses more USB DPRAM, but offers better performance. Isochronous type pipes <b>must</b>
* have at least two banks.
*
- * \note When the \c ORDERED_EP_CONFIG compile time option is used, Pipes <b>must</b> be configured in ascending order,
- * or bank corruption will occur.
- * \n\n
+ * \attention When the \c ORDERED_EP_CONFIG compile time option is used, Pipes <b>must</b> be configured in ascending order,
+ * or bank corruption will occur.
*
* \note Certain microcontroller model's pipes may have different maximum packet sizes based on the pipe's
* index - refer to the chosen microcontroller's datasheet to determine the maximum bank size for each pipe.
* function prototype.
* \n\n
*
- * \note To reduce the FLASH requirements of the library if only fixed settings are are required,
+ * \note To reduce the FLASH requirements of the library if only fixed settings are required,
* the options may be set statically in the same manner as the mode (see the Mode parameter of
* this function). To statically set the USB options, pass in the \c USE_STATIC_OPTIONS token,
* defined to the appropriate options masks. When the options are statically set, this
/** Indicates the mode that the USB interface is currently initialized to, a value from the
* \ref USB_Modes_t enum.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
- * \n\n
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \note When the controller is initialized into UID auto-detection mode, this variable will hold the
* currently selected USB mode (i.e. \ref USB_MODE_Device or \ref USB_MODE_Host). If the controller
/** 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 \c USB_MODE_* masks defined elsewhere in this module.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
extern volatile uint8_t USB_Options;
#elif defined(USE_STATIC_OPTIONS)
* different configurations which the host can select between; this indicates the currently selected
* value, or 0 if no configuration has been selected.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \ingroup Group_Device
*/
/** Indicates if the host is currently allowing the device to issue remote wakeup events. If this
* flag is cleared, the device should not issue remote wakeup events to the host.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
- * \n\n
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \note To reduce FLASH usage of the compiled applications where Remote Wakeup is not supported,
* this global and the underlying management code can be disabled by defining the
* This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
* two seconds) will prevent the device from enumerating correctly.
*
+ * \attention This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
+ * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
+ *
* \note For the microcontrollers with limited USB controller functionality, VBUS sensing is not available.
* this means that the current connection state is derived from the bus suspension and wake up events by default,
* which is not always accurate (host may suspend the bus while still connected). If the actual connection state
* and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
* \n\n
*
- * \note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
- * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
- *
* \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
*/
void EVENT_USB_Device_Connect(void);
/** Event for USB device disconnection. This event fires when the microcontroller is in USB Device mode and the device is
* disconnected from a host, measured by a falling level on the microcontroller's VBUS sense pin.
*
+ * \attention This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
+ * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
+ *
* \note For the microcontrollers with limited USB controllers, VBUS sense is not available to the USB controller.
* this means that the current connection state is derived from the bus suspension and wake up events by default,
* which is not always accurate (host may suspend the bus while still connected). If the actual connection state
* and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.
* \n\n
*
- * \note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
- * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
- *
* \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
*/
void EVENT_USB_Device_Disconnect(void);
*
* To set a device configuration, call the \ref USB_Host_SetDeviceConfiguration() function.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \ingroup Group_Host
*/
* USB interface should be initialized in low speed (1.5Mb/s) mode.
*
* \note Restrictions apply on the number, size and type of endpoints which can be used
- * when running in low speed mode - refer to the USB 2.0 specification.
+ * when running in low speed mode - please refer to the USB 2.0 specification.
*/
#define USB_DEVICE_OPT_LOWSPEED (1 << 0)
* Typically, this is implemented so that HID devices (mice, keyboards, etc.) can wake up the
* host computer when the host has suspended all USB devices to enter a low power state.
*
- * \note This macro should only be used if the device has indicated to the host that it
+ * \note This function 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 \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
- * compile time option is used, this macro is unavailable.
- * \n\n
+ * compile time option is used, this function is unavailable.
*
* \note The USB clock must be running for this function to operate. If the stack is initialized with
* the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
/** Retrieves the maximum bank size in bytes of a given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
/** Retrieves the total number of banks supported by the given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
* More banks uses more USB DPRAM, but offers better performance. Isochronous type
* endpoints <b>must</b> have at least two banks.
*
- * \note When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
- * ascending order, or bank corruption will occur.
- * \n\n
+ * \attention When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
+ * ascending order, or bank corruption will occur.
*
* \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
* the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
/** Indicates the number of bytes currently stored in the current endpoint's selected bank.
*
- * \note The return width of this function may differ, depending on the maximum endpoint bank size
- * of the selected AVR model.
- *
* \ingroup Group_EndpointRW_UC3
*
* \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
* \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
* be used in the device descriptors to ensure this.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
#if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
extern uint8_t USB_Device_ControlEndpointSize;
/** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
* with respect to the data direction. This is a convenience function which can be used to
* simplify user control request handling.
+ *
+ * \note This routine should not be called on non CONTROL type endpoints.
*/
void Endpoint_ClearStatusStage(void);
* \ref EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when a device is enumerated while in host mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_EnableSOFEvents(void)
/** Disables the host mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.
*
- * \note Not available when the NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_DisableSOFEvents(void)
/* Inline Functions: */
/** Indicates the number of bytes currently stored in the current pipes's selected bank.
*
- * \note The return width of this function may differ, depending on the maximum pipe bank size
- * of the selected AVR model.
- *
* \ingroup Group_PipeRW_UC3
*
* \return Total number of bytes in the currently selected pipe's FIFO buffer.
* descriptor once the USB interface is initialized into host mode and a device is attached
* to the USB bus.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
extern uint8_t USB_Host_ControlPipeSize;
* function prototype.
* \n\n
*
- * \note To reduce the FLASH requirements of the library if only fixed settings are are required,
+ * \note To reduce the FLASH requirements of the library if only fixed settings are required,
* the options may be set statically in the same manner as the mode (see the Mode parameter of
* this function). To statically set the USB options, pass in the \c USE_STATIC_OPTIONS token,
* defined to the appropriate options masks. When the options are statically set, this
/** Indicates the mode that the USB interface is currently initialized to, a value from the
* \ref USB_Modes_t enum.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
- * \n\n
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \note When the controller is initialized into UID auto-detection mode, this variable will hold the
* currently selected USB mode (i.e. \ref USB_MODE_Device or \ref USB_MODE_Host). If the controller
/** 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 \c USB_MODE_* masks defined elsewhere in this module.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
extern volatile uint8_t USB_Options;
#elif defined(USE_STATIC_OPTIONS)
* or device (i.e. if \ref USB_Init() has been run). If this is false, all other library globals related
* to the USB driver are invalid.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \ingroup Group_USBManagement
*/
* the compiler via the -D switch. When defined, the corresponding GPIOR register should not be used
* in the user application except implicitly via the library APIs.
*
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value except in the circumstances outlined above.
+ *
* \note This global is only present if the user application can be a USB device.
* \n\n
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value except in the circumstances outlined above.
- *
* \see \ref USB_Device_States_t for a list of possible device states.
*
* \ingroup Group_Device
* Typically, this is implemented so that HID devices (mice, keyboards, etc.) can wake up the
* host computer when the host has suspended all USB devices to enter a low power state.
*
- * \note This macro should only be used if the device has indicated to the host that it
+ * \note This function 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 \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
- * compile time option is used, this macro is unavailable.
+ * compile time option is used, this function is unavailable.
* \n\n
*
* \note The USB clock must be running for this function to operate. If the stack is initialized with
* \ref EVENT_USB_Device_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when enumerated in device mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_EnableSOFEvents(void)
/** Disables the device mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Device_StartOfFrame() event when enumerated in device mode.
*
- * \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
+ * \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_DisableSOFEvents(void)
/** Retrieves the maximum bank size in bytes of a given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
/** Retrieves the total number of banks supported by the given endpoint.
*
- * \note This macro will only work correctly on endpoint indexes that are compile-time constants
- * defined by the preprocessor.
+ * \attention This macro will only work correctly on endpoint indexes that are compile-time constants
+ * defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
/** Indicates the number of bytes currently stored in the current endpoint's selected bank.
*
- * \note The return width of this function may differ, depending on the maximum endpoint bank size
- * of the selected AVR model.
- *
* \ingroup Group_EndpointRW_XMEGA
*
* \return Total number of bytes in the currently selected Endpoint's FIFO buffer.
* \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
* be used in the device descriptors to ensure this.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
#if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
extern uint8_t USB_Device_ControlEndpointSize;
/** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
* with respect to the data direction. This is a convenience function which can be used to
* simplify user control request handling.
+ *
+ * \note This routine should not be called on non CONTROL type endpoints.
*/
void Endpoint_ClearStatusStage(void);
* function prototype.
* \n\n
*
- * \note To reduce the FLASH requirements of the library if only fixed settings are are required,
+ * \note To reduce the FLASH requirements of the library if only fixed settings are required,
* the options may be set statically in the same manner as the mode (see the Mode parameter of
* this function). To statically set the USB options, pass in the \c USE_STATIC_OPTIONS token,
* defined to the appropriate options masks. When the options are statically set, this
/** Indicates the mode that the USB interface is currently initialized to, a value from the
* \ref USB_Modes_t enum.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
- * \n\n
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*
* \note When the controller is initialized into UID auto-detection mode, this variable will hold the
* currently selected USB mode (i.e. \ref USB_MODE_Device or \ref USB_MODE_Host). If the controller
/** 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 \c USB_MODE_* masks defined elsewhere in this module.
*
- * \note This variable should be treated as read-only in the user application, and never manually
- * changed in value.
+ * \attention This variable should be treated as read-only in the user application, and never manually
+ * changed in value.
*/
extern volatile uint8_t USB_Options;
#elif defined(USE_STATIC_OPTIONS)
* before the class driver is used. Each Device mode Class driver typically contains a set of configuration parameters
* for the endpoint size/number of the associated logical USB interface, plus any class-specific configuration parameters.
*
- * \note The \c State section of the \c USB_ClassInfo_* structures are designed to be controlled by the Class Drivers only
- * for maintaining the Class Driver instance's state, and should not normally be altered by the user application.
- *
* The following is an example of a properly initialized instance of the Audio Class Driver structure:
*
* \code
* before the class driver is used. Each Device mode Class driver typically contains a set of configuration parameters
* for the endpoint size/number of the associated logical USB interface, plus any class-specific configuration parameters.
*
- * \note The \c State section of the \c USB_ClassInfo_* structures are designed to be controlled by the Class Drivers only
- * for maintaining the Class Driver instance's state, and should not normally be altered by the user application.
- *
* The following is an example of a properly initialized instance of the MIDI Host Class Driver structure:
*
* \code
/** Starts the given PLL of the UC3 microcontroller, with the given options. This routine blocks until the PLL is ready for use.
*
- * \note The output frequency must be equal to or greater than the source frequency.
+ * \attention The output frequency must be equal to or greater than the source frequency.
*
* \param[in] Channel Index of the PLL to start.
* \param[in] Source Clock source for the PLL, a value from \ref UC3_System_ClockSource_t.
/** Starts the PLL of the XMEGA microcontroller, with the given options. This routine blocks until the PLL is ready for use.
*
- * \note The output frequency must be equal to or greater than the source frequency.
+ * \attention The output frequency must be equal to or greater than the source frequency.
*
* \param[in] Source Clock source for the PLL, a value from \ref XMEGA_System_ClockSource_t.
* \param[in] SourceFreq Frequency of the PLL's clock source, in Hz.
/** Contains the total number of tasks in the task list, irrespective of if the task's status is set to
* \ref TASK_RUN or \ref TASK_STOP.
*
- * \note This value should be treated as read-only, and never altered in user-code.
+ * \warning This value should be treated as read-only, and never altered in user-application code.
*/
extern volatile uint_least8_t Scheduler_TotalTasks;
projects / pub / USBasp.git / commitdiff