projects / pub / USBasp.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Applied STATIC_ENDPOINT_CONFIGURATION and FIXED_CONTROL_SIZE tokens to all Device...
[pub/USBasp.git] / LUFA / Drivers / USB / HighLevel / Events.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2009.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, and distribute this software
13 and its documentation for any purpose and without fee is hereby
14 granted, provided that the above copyright notice appear in all
15 copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \ingroup Group_USB
32 * @defgroup Group_Events USB Events
33 *
34 * This module contains macros and functions relating to the management of library events, which are small
35 * pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from
36 * multiple places in the user or library code, which may or may not be inside an ISR, thus each handler
37 * should be written to be as small and fast as possible to prevent possible problems.
38 *
39 * Events can be hooked by the user application using the EVENT_HANDLER() and HANDLES_EVENT() macros. If an
40 * event with no associated handler is fired within the library, it by default fires an internal empty stub
41 * function. This is achieved through the use of the GCC compiler's "alias" attribute.
42 *
43 * Each event must only have one associated event handler, but can be raised by multiple sources.
44 *
45 * @{
46 */
47
48 #ifndef __USBEVENTS_H__
49 #define __USBEVENTS_H__
50
51 /* Includes: */
52 #include <avr/io.h>
53
54 #include "../../../Common/Common.h"
55 #include "USBMode.h"
56
57 /* Enable C linkage for C++ Compilers: */
58 #if defined(__cplusplus)
59 extern "C" {
60 #endif
61
62 /* Public Interface - May be used in end-application: */
63 /* Macros: */
64 /** Raises a given event name, with the specified parameters. For events with no parameters the
65 * only argument to the macro is the event name, events with parameters list the parameter values
66 * after the name as a comma separated list.
67 *
68 * When a given event is fired, its corresponding event handler code is executed.
69 *
70 * Usage Examples:
71 * \code
72 * // Raise the USB_VBUSChange event, which takes no parameters
73 * RAISE_EVENT(USB_VBUSChange);
74 *
75 * // Raise the USB_UnhandledControlPacket event which takes two parameters
76 * RAISE_EVENT(USB_UnhandledControlPacket, 0, 1);
77 * \endcode
78 *
79 * \see RAISES_EVENT()
80 */
81 #define RAISE_EVENT(e, ...) Event_ ## e (__VA_ARGS__)
82
83 /** Indicates that a given module can raise a given event. This is the equivalent of putting the
84 * event function's prototype into the module, but in a cleaner way. Each event which may be
85 * fired via the RAISE_EVENT macro in the module should have an accompanying RAISES_EVENT
86 * prototype in the module's header file.
87 *
88 * Usage Examples:
89 * \code
90 * // Module can raise the USB_VBUSChange event
91 * RAISES_EVENT(USB_VBUSChange);
92 *
93 * // ...
94 * // Inside a block of code in a function of the module, raise the USB_VBUSChange event
95 * RAISE_EVENT(USB_VBUSChange);
96 * \endcode
97 *
98 * \see RAISE_EVENT()
99 */
100 #define RAISES_EVENT(e) HANDLES_EVENT(e)
101
102 /** Defines an event handler for the given event. Event handlers should be short in length, as they
103 * may be raised from inside an ISR. The user application can react to each event as it sees fit,
104 * such as logging the event, indicating the change to the user or performing some other action.
105 *
106 * Only one event handler may be defined in any user project for each individual event. Events may
107 * or may not have parameters - for each event, refer to its documentation elsewhere in this module
108 * to determine the presence and purpose of any event parameters.
109 *
110 * Usage Example:
111 * \code
112 * // Create an event handler for the USB_VBUSChange event
113 * EVENT_HANDLER(USB_VBUSChange)
114 * {
115 * // Code to execute when the VBUS level changes
116 * }
117 * \endcode
118 *
119 * \see HANDLES_EVENT()
120 */
121 #define EVENT_HANDLER(e) void Event_ ## e e ## _P
122
123 /** Indicates that a given module handles an event. This is the equivalent of putting the
124 * event function's prototype into the module, but in a cleaner way. Each event which may be
125 * handled via the EVENT_HANDLER macro in the module should have an accompanying HANDLES_EVENT
126 * prototype in the module's header file.
127 *
128 * Usage Examples:
129 * \code
130 * // Module handles the USB_VBUSChange event
131 * HANDLES_EVENT(USB_VBUSChange);
132 *
133 * // Create the USB_VBUSChange event handler
134 * EVENT_HANDLER(USB_VBUSChange)
135 * {
136 * // Event handler code here
137 * }
138 * \endcode
139 *
140 * \see EVENT_HANDLER()
141 */
142 #define HANDLES_EVENT(e) EVENT_HANDLER(e)
143
144 /* Pseudo-Functions for Doxygen: */
145 #if defined(__DOXYGEN__)
146 /** Event for VBUS level change. This event fires when the VBUS line of the USB AVR changes from
147 * high to low or vice-versa.
148 *
149 * \note This event is only available on USB AVR models which support VBUS notification interrupts.
150 */
151 void USB_VBUSChange(void);
152
153 /** Event for VBUS attachment. This event fires when the VBUS line of the USB AVR changes from
154 * low to high, signalling the attachment of the USB device to a host, before the enumeration
155 * process has begun.
156 *
157 * \note This event is only available on USB AVR models which support VBUS notification interrupts.
158 */
159 void USB_VBUSConnect(void);
160
161 /** Event for VBUS detachment. This event fires when the VBUS line of the USB AVR changes from
162 * high to low, signalling the USB device has been removed from a host whether it has been enumerated
163 * or not.
164 *
165 * \note This event is only available on USB AVR models which support VBUS notification interrupts.
166 */
167 void USB_VBUSDisconnect(void);
168
169 /** Event for USB device connection. This event fires when the AVR is in USB host mode and a device
170 * has been attached (but not yet fully enumerated), or when in device mode and the device is connected
171 * to a host, beginning the enumeration process.
172 *
173 * When in device mode, this can be used to programmatically start the USB management task to reduce
174 * CPU usage.
175 *
176 * \note For the smaller USB AVRs (AT90USBXX2) with limited USB controllers, VBUS is not available to the USB controller.
177 * this means that the current connection state is derived from the bus suspension and wake up events by default,
178 * which is not always accurate (host may suspend the bus while still connected). If the actual connection state
179 * needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
180 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
181 * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually.
182 *
183 * \see USBTask.h for more information on the USB management task and reducing CPU usage.
184 */
185 void USB_Connect(void);
186
187 /** Event for USB device disconnection. This event fires when the AVR is in USB host mode and an
188 * attached and enumerated device has been disconnected, or when in device mode and the device is
189 * disconnected from the host.
190 *
191 * When in device mode, this can be used to programmatically stop the USB management task to reduce
192 * CPU usage.
193 *
194 * \note For the smaller USB AVRs (AT90USBXX2) with limited USB controllers, VBUS is not available to the USB controller.
195 * this means that the current connection state is derived from the bus suspension and wake up events by default,
196 * which is not always accurate (host may suspend the bus while still connected). If the actual connection state
197 * needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
198 * passing the NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
199 * and disconnection events may be manually fired by RAISE_EVENT(), and the USB_IsConnected global changed manually.
200 *
201 * \see USBTask.h for more information on the USB management task and reducing CPU usage.
202 */
203 void USB_Disconnect(void);
204
205 /** Event for USB device power on failure. This event fires when the USB interface fails to
206 * initialize correctly due to a hardware or software fault.
207 *
208 * \param ErrorCode Error code indicating the failure reason, a value in USB_PowerOnErrorCodes_t
209 * located in LowLevel.h.
210 */
211 void USB_PowerOnFail(const uint8_t ErrorCode);
212
213 /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role
214 * mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires
215 * before the mode is switched to the newly indicated mode.
216 *
217 * \note This event only exists on USB AVR models which support dual role modes.
218 *
219 * \note This event does not exist if the USB_DEVICE_ONLY or USB_HOST_ONLY tokens have been supplied
220 * to the compiler (see LowLevel.h documentation).
221 */
222 void USB_UIDChange(void);
223
224 /** Event for USB host error. This event fires when a hardware fault has occurred whilst the USB
225 * interface is in host mode.
226 *
227 * \param ErrorCode Error code indicating the failure reason, a value in USB_Host_ErrorCodes_t
228 * located in Host.h.
229 *
230 * \note This event only exists on USB AVR models which supports host mode.
231 *
232 * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
233 * LowLevel.h documentation).
234 */
235 void USB_HostError(const uint8_t ErrorCode);
236
237 /** Event for USB device attachment. This event fires when a the USB interface is in host mode, and
238 * a USB device has been connected to the USB interface. This is interrupt driven, thus fires before
239 * the standard USB_DeviceConnect event and so can be used to programmatically start the USB management
240 * task to reduce CPU consumption.
241 *
242 * \note This event only exists on USB AVR models which supports host mode.
243 *
244 * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
245 * LowLevel.h documentation).
246 *
247 * \see USBTask.h for more information on the USB management task and reducing CPU usage.
248 */
249 void USB_DeviceAttached(void);
250
251 /** Event for USB device removal. This event fires when a the USB interface is in host mode, and
252 * a USB device has been removed the USB interface whether or not it has been enumerated. This
253 * can be used to programmatically stop the USB management task to reduce CPU consumption.
254 *
255 * \note This event only exists on USB AVR models which supports host mode.
256 *
257 * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
258 * LowLevel.h documentation).
259 *
260 * \see USBTask.h for more information on the USB management task and reducing CPU usage.
261 */
262 void USB_DeviceUnattached(void);
263
264 /** Event for USB device enumeration failure. This event fires when a the USB interface is
265 * in host mode, and an attached USB device has failed to enumerate completely.
266 *
267 * \param ErrorCode Error code indicating the failure reason, a value in
268 * USB_Host_EnumerationErrorCodes_t located in Host.h.
269 *
270 * \param SubErrorCode Sub error code indicating the reason for failure - for example, if the
271 * ErrorCode parameter indicates a control error, this will give the error
272 * code returned by the USB_Host_SendControlRequest() function.
273 *
274 * \note This event only exists on USB AVR models which supports host mode.
275 *
276 * \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
277 * LowLevel.h documentation).
278 */
279 void USB_DeviceEnumerationFailed(const uint8_t ErrorCode, const uint8_t SubErrorCode);
280
281 /** Event for USB device enumeration completion. This event fires when a the USB interface is
282 * in host mode and an attached USB device has been completely enumerated and is ready to be
283 * controlled by the user application, or when the library is in device mode, and the Host
284 * has finished enumerating the device.
285 */
286 void USB_DeviceEnumerationComplete(void);
287
288 /** Event for unhandled control requests. This event fires when a the USB host issues a control
289 * request to the control endpoint (address 0) that the library does not handle. This may either
290 * be a standard request that the library has no handler code for, or a class specific request
291 * issued to the device which must be handled appropriately. Due to the strict timing requirements
292 * on control transfers, interrupts are disabled during control request processing.
293 *
294 * \param bRequest Request value, indicating what command the host has issued.
295 * \param bmRequestType Mask indicating the request data direction (if any), type and recipient.
296 *
297 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
298 * LowLevel.h documentation).
299 *
300 * \note Requests should be handled in the same manner as described in the USB 2.0 Specification,
301 * or appropriate class' specification. In all instances, the library has already read the
302 * request bmRequestType and bRequest values out (into the Request and RequestType parameters
303 * respectively) so that it can correctly determine if it is able to handle the request
304 * internally, or hand off the request to the user application via this event. Other request
305 * parameters (wValue, wIndex, wLength, and Data) remain in the control endpoint bank until
306 * read out by the user application for processing.
307 */
308 void USB_UnhandledControlPacket(void);
309
310 /** Event for USB configuration number changed. This event fires when a the USB host changes the
311 * selected configuration number while in device mode. This event should be hooked in device
312 * applications to create the endpoints and configure the device for the selected configuration.
313 *
314 * This event fires after the value of USB_ConfigurationNumber has been changed.
315 *
316 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
317 * LowLevel.h documentation).
318 */
319 void USB_ConfigurationChanged(void);
320
321 /** Event for USB suspend. This event fires when a the USB host suspends the device by halting its
322 * transmission of Start Of Frame pulses to the device. This is generally hooked in order to move
323 * the device over to a low power state until the host wakes up the device.
324 *
325 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
326 * LowLevel.h documentation).
327 *
328 * \see USB_WakeUp() event for accompanying Wake Up event.
329 */
330 void USB_Suspend(void);
331
332 /** Event for USB wake up. This event fires when a the USB interface is suspended while in device
333 * mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally
334 * hooked to pull the user application out of a lowe power state and back into normal operating
335 * mode.
336 *
337 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
338 * LowLevel.h documentation).
339 *
340 * \see USB_Suspend() event for accompanying Suspend event.
341 */
342 void USB_WakeUp(void);
343
344 /** Event for USB interface reset. This event fires when a the USB interface is in device mode, and
345 * a the USB host requests that the device reset its interface. This is generally hooked so that
346 * the USB control endpoint can be switched to interrupt driven mode, by selecting it and calling
347 * USB_INT_Enable(ENDPOINT_INT_SETUP). Before this event fires, all device endpoints are reset and
348 * disabled.
349 *
350 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
351 * LowLevel.h documentation).
352 */
353 void USB_Reset(void);
354
355 /** Event for USB device mode error. This event fires when the USB interface is in device mode,
356 * and an error occurs which prevents it from operating normally.
357 *
358 * \param ErrorCode Error code indicating the source of the error. One of the values in the
359 * USB_Device_ErrorCodes_t enum located in Device.h.
360 *
361 * \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
362 * LowLevel.h documentation).
363 */
364 void USB_DeviceError(const uint8_t ErrorCode);
365 #endif
366
367 /* Private Interface - For use in library only: */
368 #if !defined(__DOXYGEN__)
369 /* Macros: */
370 #define ALIAS_STUB(e) EVENT_HANDLER(e) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub)
371
372 #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
373 #define USB_VBUSChange_P (void)
374 #define USB_VBUSConnect_P (void)
375 #define USB_VBUSDisconnect_P (void)
376 #endif
377
378 #define USB_Connect_P (void)
379 #define USB_Disconnect_P (void)
380 #define USB_DeviceEnumerationComplete_P (void)
381
382 #if defined(USB_CAN_BE_BOTH)
383 #define USB_PowerOnFail_P (const uint8_t ErrorCode)
384 #define USB_UIDChange_P (void)
385 #endif
386
387 #if defined(USB_CAN_BE_HOST)
388 #define USB_HostError_P (const uint8_t ErrorCode)
389 #define USB_DeviceAttached_P (void)
390 #define USB_DeviceUnattached_P (void)
391 #define USB_DeviceEnumerationFailed_P (const uint8_t ErrorCode, const uint8_t SubErrorCode)
392 #endif
393
394 #if defined(USB_CAN_BE_DEVICE)
395 #define USB_UnhandledControlPacket_P (void)
396 #define USB_ConfigurationChanged_P (void)
397 #define USB_Suspend_P (void)
398 #define USB_WakeUp_P (void)
399 #define USB_Reset_P (void)
400 #define USB_DeviceError_P (const uint8_t ErrorCode)
401 #endif
402
403 /* Function Prototypes: */
404 #if defined(INCLUDE_FROM_EVENTS_C)
405 void USB_Event_Stub (void) ATTR_CONST;
406
407 #if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
408 ALIAS_STUB(USB_VBUSChange);
409 ALIAS_STUB(USB_VBUSConnect);
410 ALIAS_STUB(USB_VBUSDisconnect);
411 #endif
412
413 ALIAS_STUB(USB_Connect);
414 ALIAS_STUB(USB_Disconnect);
415 ALIAS_STUB(USB_DeviceEnumerationComplete);
416
417 #if defined(USB_CAN_BE_BOTH)
418 ALIAS_STUB(USB_PowerOnFail);
419 ALIAS_STUB(USB_UIDChange);
420 #endif
421
422 #if defined(USB_CAN_BE_HOST)
423 ALIAS_STUB(USB_HostError);
424 ALIAS_STUB(USB_DeviceAttached);
425 ALIAS_STUB(USB_DeviceUnattached);
426 ALIAS_STUB(USB_DeviceEnumerationFailed);
427 #endif
428
429 #if defined(USB_CAN_BE_DEVICE)
430 ALIAS_STUB(USB_UnhandledControlPacket);
431 ALIAS_STUB(USB_ConfigurationChanged);
432 ALIAS_STUB(USB_Suspend);
433 ALIAS_STUB(USB_WakeUp);
434 ALIAS_STUB(USB_Reset);
435 ALIAS_STUB(USB_DeviceError);
436 #endif
437 #endif
438 #endif
439
440 /* Disable C linkage for C++ Compilers: */
441 #if defined(__cplusplus)
442 }
443 #endif
444
445 #endif
446
447 /** @} */
USB isp AVR programmer