/*
LUFA Library
- Copyright (C) Dean Camera, 2010.
-
+ Copyright (C) Dean Camera, 2011.
+
dean [at] fourwalledcubicle [dot] com
- www.fourwalledcubicle.com
+ www.lufa-lib.org
*/
/*
- Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)
+ Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)
- Permission to use, copy, modify, distribute, and sell this
+ Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby granted
- without fee, provided that the above copyright notice appear in
+ without fee, provided that the above copyright notice appear in
all copies and that both that the copyright notice and this
- permission notice and warranty disclaimer appear in supporting
- documentation, and that the name of the author not be used in
- advertising or publicity pertaining to distribution of the
+ permission notice and warranty disclaimer appear in supporting
+ documentation, and that the name of the author not be used in
+ advertising or publicity pertaining to distribution of the
software without specific, written prior permission.
The author disclaim all warranties with regard to this
*
* @{
*/
-
+
#ifndef __USBEVENTS_H__
#define __USBEVENTS_H__
/* Includes: */
#include <stdint.h>
-
+
#include "../../../Common/Common.h"
#include "USBMode.h"
#if !defined(__INCLUDE_FROM_USB_DRIVER)
#error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
#endif
-
- /* Public Interface - May be used in end-application: */
+
+ /* Public Interface - May be used in end-application: */
/* Pseudo-Functions for Doxygen: */
#if !defined(__INCLUDE_FROM_EVENTS_C) || defined(__DOXYGEN__)
/** Event for USB mode pin level change. This event fires when the USB interface is set to dual role
* \note This event only exists on USB AVR models which support dual role modes.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY or USB_HOST_ONLY tokens have been supplied
+ * \note This event does not exist if the \c USB_DEVICE_ONLY or \c USB_HOST_ONLY tokens have been supplied
* to the compiler (see \ref Group_USBManagement documentation).
*/
void EVENT_USB_UIDChange(void);
* \note This event only exists on USB AVR models which supports host mode.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Host_HostError(const uint8_t ErrorCode);
-
+
/** 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 \ref EVENT_USB_Device_Connect() event and so can be used to programmatically start the USB
* \note This event only exists on USB AVR models which supports host mode.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*
* \see \ref USB_USBTask() for more information on the USB management task and reducing CPU usage.
* \note This event only exists on USB AVR models which supports host mode.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*
* \see \ref USB_USBTask() for more information on the USB management task and reducing CPU usage.
*/
void EVENT_USB_Host_DeviceUnattached(void);
-
+
/** Event for USB device enumeration failure. This event fires when a the USB interface is
* in host mode, and an attached USB device has failed to enumerate completely.
*
- * \param[in] ErrorCode Error code indicating the failure reason, a value in
+ * \param[in] ErrorCode Error code indicating the failure reason, a value in
* \ref USB_Host_EnumerationErrorCodes_t.
*
* \param[in] SubErrorCode Sub error code indicating the reason for failure - for example, if the
* \note This event only exists on USB AVR models which supports host mode.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Host_DeviceEnumerationFailed(const uint8_t ErrorCode,
* a USB device.
* \n\n
*
- * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Host_StartOfFrame(void);
* 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
* 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
+ * passing the \c NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
* 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 series 2 USB AVRs with limited USB controllers
- * if NO_LIMITED_CONTROLLER_CONNECT is not defined.
+ * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
*
- * \see USBTask.h for more information on the USB management task and reducing CPU usage.
+ * \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
*/
void EVENT_USB_Device_Connect(void);
* 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
* 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
+ * passing the \c NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
* 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 series 2 USB AVRs with limited USB controllers
- * if NO_LIMITED_CONTROLLER_CONNECT is not defined.
+ * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
*
- * \see USBTask.h for more information on the USB management task and reducing CPU usage.
+ * \see \ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
*/
void EVENT_USB_Device_Disconnect(void);
- /** Event for unhandled control requests. This event fires when a the USB host issues a control
- * request to the control endpoint (address 0) that the library does not handle. This may either
- * be a standard request that the library has no handler code for, or a class specific request
- * issued to the device which must be handled appropriately.
+ /** Event for control requests. This event fires when a the USB host issues a control request
+ * to the mandatory device control endpoint (of address 0). This may either be a standard
+ * request that the library may have a handler code for internally, or a class specific request
+ * issued to the device which must be handled appropriately. If a request is not processed in the
+ * user application via this event, it will be passed to the library for processing internally
+ * if a suitable handler exists.
*
* This event is time-critical; each packet within the request transaction must be acknowledged or
* sent within 50ms or the host will abort the transfer.
*
* The library internally handles all standard control requests with the exceptions of SYNC FRAME,
* SET DESCRIPTOR and SET INTERFACE. These and all other non-standard control requests will be left
- * for the user to process via this event if desired. If not handled in the user application, requests
- * are automatically STALLed.
+ * for the user to process via this event if desired. If not handled in the user application or by
+ * the library internally, unknown requests are automatically STALLed.
*
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
* \n\n
*
* 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 EVENT_USB_Device_UnhandledControlRequest(void);
+ void EVENT_USB_Device_ControlRequest(void);
/** Event for USB configuration number changed. This event fires when a the USB host changes the
* selected configuration number while in device mode. This event should be hooked in device
*
* 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
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Device_ConfigurationChanged(void);
* enumerated with the \ref USB_OPT_AUTO_PLL option set, the library will automatically suspend the
* USB PLL before the event is fired to save power.
*
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
* \n\n
*
- * \note This event does not exist on the series 2 USB AVRs when the NO_LIMITED_CONTROLLER_CONNECT
+ * \note This event does not exist on the series 2 USB AVRs when the \c NO_LIMITED_CONTROLLER_CONNECT
* compile time token is not set - see \ref EVENT_USB_Device_Disconnect.
*
* \see \ref EVENT_USB_Device_WakeUp() event for accompanying Wake Up event.
* mode. If the USB interface is enumerated with the \ref USB_OPT_AUTO_PLL option set, the library
* will automatically restart the USB PLL before the event is fired.
*
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
* \n\n
*
- * \note This event does not exist on the series 2 USB AVRs when the NO_LIMITED_CONTROLLER_CONNECT
+ * \note This event does not exist on the series 2 USB AVRs when the \c NO_LIMITED_CONTROLLER_CONNECT
* compile time token is not set - see \ref EVENT_USB_Device_Connect.
*
* \see \ref EVENT_USB_Device_Suspend() event for accompanying Suspend event.
* 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.
*
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Device_Reset(void);
* This event is time-critical; it is run once per millisecond and thus long handlers will significantly
* degrade device performance. This event should only be enabled when needed to reduce device wake-ups.
*
- * \note This event is not normally active - it must be manually enabled and disabled via the
- * \ref USB_Device_EnableSOFEvents() and \ref USB_Device_DisableSOFEvents() commands after enumeration.
- * \n\n
+ * \pre This event is not normally active - it must be manually enabled and disabled via the
+ * \ref USB_Device_EnableSOFEvents() and \ref USB_Device_DisableSOFEvents() commands after enumeration.
+ * \n\n
*
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
+ * \note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
* \ref Group_USBManagement documentation).
*/
void EVENT_USB_Device_StartOfFrame(void);
#endif
-
+
/* Private Interface - For use in library only: */
#if !defined(__DOXYGEN__)
/* Function Prototypes: */
#if defined(__INCLUDE_FROM_EVENTS_C)
void USB_Event_Stub(void) ATTR_CONST;
-
+
#if defined(USB_CAN_BE_BOTH)
void EVENT_USB_UIDChange(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
#endif
-
+
#if defined(USB_CAN_BE_HOST)
void EVENT_USB_Host_HostError(const uint8_t ErrorCode) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
void EVENT_USB_Host_DeviceAttached(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
#if defined(USB_CAN_BE_DEVICE)
void EVENT_USB_Device_Connect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
void EVENT_USB_Device_Disconnect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
- void EVENT_USB_Device_UnhandledControlRequest(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
+ void EVENT_USB_Device_ControlRequest(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
void EVENT_USB_Device_ConfigurationChanged(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
void EVENT_USB_Device_Suspend(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
void EVENT_USB_Device_WakeUp(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
#if defined(__cplusplus)
}
#endif
-
+
#endif
/** @} */
+
projects / pub / USBasp.git / blobdiff