X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/c8b72f955f1fd17dbc90254b56e6596ba70660cd..03ee87b35abdb8b92e8b55ec040fa943f9a6786c:/LUFA/Drivers/USB/HighLevel/Events.h diff --git a/LUFA/Drivers/USB/HighLevel/Events.h b/LUFA/Drivers/USB/HighLevel/Events.h index 5a007ff2a..08727d749 100644 --- a/LUFA/Drivers/USB/HighLevel/Events.h +++ b/LUFA/Drivers/USB/HighLevel/Events.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, 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 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 + 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 software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -40,7 +40,8 @@ * listed here. If an event with no user-associated handler is fired within the library, it by default maps to an * internal empty stub function. * - * Each event must only have one associated event handler, but can be raised by multiple sources. + * Each event must only have one associated event handler, but can be raised by multiple sources by calling the + * event handler function (with any required event parameters). * * @{ */ @@ -142,12 +143,19 @@ /** Event for USB device enumeration completion. This event fires when a the USB interface is * in host mode and an attached USB device has been completely enumerated and is ready to be * controlled by the user application. + * + * This event is time-critical; exceeding OS-specific delays within this event handler (typically of around + * 1 second) when a transaction is waiting to be processed by the device will prevent break communications + * and cause the host to reset the USB bus. */ void EVENT_USB_Host_DeviceEnumerationComplete(void); /** Event for USB device connection. This event fires when the AVR in device mode and the device is connected * to a host, beginning the enumeration process, measured by a rising level on the AVR's VBUS pin. * + * 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 For the smaller series 2 USB AVRs with limited USB controllers, VBUS 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 @@ -182,8 +190,15 @@ /** 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. Due to the strict timing requirements - * on control transfers, interrupts are disabled during control request processing. + * issued to the device which must be handled appropriately. + * + * 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 interally 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. * * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * \ref Group_USBManagement documentation). @@ -199,6 +214,9 @@ * 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 is time-critical; exceeding OS-specific delays within this event handler (typically of around + * one second) will prevent the device from enumerating correctly. + * * 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 @@ -215,19 +233,25 @@ * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * \ref Group_USBManagement documentation). * + * \note This event does not exist on the series 2 USB AVRs when the 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. */ void EVENT_USB_Device_Suspend(void); /** Event for USB wake up. This event fires when a the USB interface is suspended while in device * mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally - * hooked to pull the user application out of a lowe power state and back into normal operating + * hooked to pull the user application out of a low power state and back into normal operating * 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 * \ref Group_USBManagement documentation). * + * \note This event does not exist on the series 2 USB AVRs when the 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. */ void EVENT_USB_Device_WakeUp(void); @@ -236,17 +260,23 @@ * a the USB host requests that the device reset its interface. This event fires after the control * endpoint has been automatically configured by the library. * + * 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 * \ref Group_USBManagement documentation). */ void EVENT_USB_Device_Reset(void); /** Event for USB Start Of Frame detection, when enabled. This event fires at the start of each USB - * frame, once per millisecond, and is synchronised to the USB bus. This can be used as an accurate + * frame, once per millisecond, and is synchronized to the USB bus. This can be used as an accurate * millisecond timer source when the USB bus is enumerated in device mode to a USB host. * - * 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. + * 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 wakeups. + * + * \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. * * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see * \ref Group_USBManagement documentation).