*\r
* Events can be hooked by the user application by declaring a handler function with the same name and parameters\r
* listed here. If an event with no user-associated handler is fired within the library, it by default maps to an\r
- * internal empty stub function. This is achieved through the use of the GCC compiler's "alias" attribute.\r
+ * internal empty stub function.\r
*\r
* Each event must only have one associated event handler, but can be raised by multiple sources.\r
*\r
/* Pseudo-Functions for Doxygen: */\r
#if !defined(INCLUDE_FROM_EVENTS_C) || defined(__DOXYGEN__)\r
/** Event for VBUS level change. This event fires when the VBUS line of the USB AVR changes from\r
- * high to low or vice-versa.\r
+ * high to low or vice-versa, before the new VBUS level is sampled and the appropriate action\r
+ * taken.\r
*\r
* \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
*/\r
void EVENT_USB_VBUSChange(void);\r
\r
- /** Event for VBUS attachment. This event fires when the VBUS line of the USB AVR changes from\r
- * low to high, signalling the attachment of the USB device to a host, before the enumeration\r
- * process has begun.\r
+ /** Event for VBUS attachment. On the AVR models with a dedicated VBUS pin, this event fires when\r
+ * the VBUS line of the USB AVR changes from low to high (after the VBUS events have been handled),\r
+ * signalling the attachment of the USB device to a host, before the enumeration process has begun.\r
*\r
* \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
*/\r
void EVENT_USB_VBUSConnect(void);\r
\r
- /** Event for VBUS detachment. This event fires when the VBUS line of the USB AVR changes from\r
- * high to low, signalling the USB device has been removed from a host whether it has been enumerated\r
- * or not.\r
+ /** Event for VBUS attachment. On the AVR models with a dedicated VBUS pin, this event fires when\r
+ * the VBUS line of the USB AVR changes from high to low (after the VBUS events have been handled),\r
+ * signalling the detatchment of the USB device from a host, regardless of its enumeration state.\r
*\r
* \note This event is only available on USB AVR models which support VBUS notification interrupts.\r
*/\r
* which is not always accurate (host may suspend the bus while still connected). If the actual connection state\r
* needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by\r
* passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection\r
- * and disconnection events may be manually fired, and the \ref USB_IsConnected global changed manually.\r
+ * and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.\r
*\r
* \see USBTask.h for more information on the USB management task and reducing CPU usage.\r
*/\r
* which is not always accurate (host may suspend the bus while still connected). If the actual connection state\r
* needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by\r
* passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection\r
- * and disconnection events may be manually fired, and the \ref USB_IsConnected global changed manually.\r
+ * and disconnection events may be manually fired, and the \ref USB_DeviceState global changed manually.\r
*\r
* \see USBTask.h for more information on the USB management task and reducing CPU usage.\r
*/\r
*\r
* \note This event only exists on USB AVR models which support dual role modes.\r
*\r
- * \param ErrorCode Error code indicating the failure reason, a value in \ref USB_InitErrorCodes_t\r
+ * \param[in] ErrorCode Error code indicating the failure reason, a value in \ref USB_InitErrorCodes_t\r
*/\r
void EVENT_USB_InitFailure(const uint8_t ErrorCode);\r
\r
/** Event for USB mode pin level change. This event fires when the USB interface is set to dual role\r
* mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires\r
- * before the mode is switched to the newly indicated mode.\r
+ * before the mode is switched to the newly indicated mode but after the \ref EVENT_USB_Disconnect event\r
+ * has fired (if connected before the role change).\r
*\r
* \note This event only exists on USB AVR models which support dual role modes.\r
*\r
/** Event for USB host error. This event fires when a hardware fault has occurred whilst the USB\r
* interface is in host mode.\r
*\r
- * \param ErrorCode Error code indicating the failure reason, a value in \ref USB_Host_ErrorCodes_t\r
+ * \param[in] ErrorCode Error code indicating the failure reason, a value in \ref USB_Host_ErrorCodes_t\r
*\r
* \note This event only exists on USB AVR models which supports host mode.\r
*\r
* \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see\r
* \ref Group_USBManagement documentation).\r
*\r
- * \see \ref TASK(USB_USBTask) for more information on the USB management task and reducing CPU usage.\r
+ * \see \ref USB_USBTask() for more information on the USB management task and reducing CPU usage.\r
*/\r
void EVENT_USB_DeviceAttached(void);\r
\r
* \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see\r
* \ref Group_USBManagement documentation).\r
*\r
- * \see \ref TASK(USB_USBTask) for more information on the USB management task and reducing CPU usage.\r
+ * \see \ref USB_USBTask() for more information on the USB management task and reducing CPU usage.\r
*/\r
void EVENT_USB_DeviceUnattached(void);\r
\r
/** Event for USB device enumeration failure. This event fires when a the USB interface is\r
* in host mode, and an attached USB device has failed to enumerate completely.\r
*\r
- * \param ErrorCode Error code indicating the failure reason, a value in \r
- * \ref USB_Host_EnumerationErrorCodes_t\r
+ * \param[in] ErrorCode Error code indicating the failure reason, a value in \r
+ * \ref USB_Host_EnumerationErrorCodes_t\r
*\r
- * \param SubErrorCode Sub error code indicating the reason for failure - for example, if the\r
- * ErrorCode parameter indicates a control error, this will give the error\r
- * code returned by the \ref USB_Host_SendControlRequest() function.\r
+ * \param[in] SubErrorCode Sub error code indicating the reason for failure - for example, if the\r
+ * ErrorCode parameter indicates a control error, this will give the error\r
+ * code returned by the \ref USB_Host_SendControlRequest() function.\r
*\r
* \note This event only exists on USB AVR models which supports host mode.\r
*\r
\r
/** Event for USB suspend. This event fires when a the USB host suspends the device by halting its\r
* transmission of Start Of Frame pulses to the device. This is generally hooked in order to move\r
- * the device over to a low power state until the host wakes up the device.\r
+ * the device over to a low power state until the host wakes up the device. If the USB interface is\r
+ * enumerated with the \ref USB_OPT_AUTO_PLL option set, the library will automatically suspend the\r
+ * USB PLL before the event is fired to save power.\r
*\r
* \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
* \ref Group_USBManagement documentation).\r
/** Event for USB wake up. This event fires when a the USB interface is suspended while in device\r
* mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally\r
* hooked to pull the user application out of a lowe power state and back into normal operating\r
- * mode.\r
+ * mode. If the USB interface is enumerated with the \ref USB_OPT_AUTO_PLL option set, the library\r
+ * will automatically restart the USB PLL before the event is fired.\r
*\r
* \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
* \ref Group_USBManagement documentation).\r
*/\r
void EVENT_USB_WakeUp(void);\r
\r
- /** Event for USB interface reset. This event fires when a the USB interface is in device mode, and\r
- * a the USB host requests that the device reset its interface. This is generally hooked so that\r
- * the USB control endpoint can be switched to interrupt driven mode, by selecting it and calling\r
- * USB_INT_Enable(ENDPOINT_INT_SETUP). Before this event fires, all device endpoints are reset and\r
- * disabled.\r
+ /** Event for USB interface reset. This event fires when the USB interface is in device mode, and\r
+ * a the USB host requests that the device reset its interface. This event fires after the control\r
+ * endpoint has been automatically configured by the library.\r
*\r
* \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
* \ref Group_USBManagement documentation).\r
*/\r
void EVENT_USB_Reset(void);\r
- \r
- /** Event for USB device mode error. This event fires when the USB interface is in device mode,\r
- * and an error occurs which prevents it from operating normally.\r
- *\r
- * \param ErrorCode Error code indicating the source of the error, a value in\r
- * \ref USB_Device_ErrorCodes_t\r
- *\r
- * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see\r
- * \ref Group_USBManagement documentation).\r
- */\r
- void EVENT_USB_DeviceError(const uint8_t ErrorCode);\r
#endif\r
\r
/* Private Interface - For use in library only: */\r
#if defined(INCLUDE_FROM_EVENTS_C)\r
void USB_Event_Stub(void) ATTR_CONST;\r
\r
- #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)\r
+ #if (defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR))\r
void EVENT_USB_VBUSChange(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
void EVENT_USB_VBUSConnect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
void EVENT_USB_VBUSDisconnect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
void EVENT_USB_Suspend(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
void EVENT_USB_WakeUp(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
void EVENT_USB_Reset(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
- void EVENT_USB_DeviceError(const uint8_t ErrorCode) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);\r
#endif\r
#endif\r
\r
projects / pub / USBasp.git / blobdiff