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