2 * @brief USB Event management definitions
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\r
10 * Software that is described herein is for illustrative purposes only
\r
11 * which provides customers with programming information regarding the
\r
12 * LPC products. This software is supplied "AS IS" without any warranties of
\r
13 * any kind, and NXP Semiconductors and its licensor disclaim any and
\r
14 * all warranties, express or implied, including all implied warranties of
\r
15 * merchantability, fitness for a particular purpose and non-infringement of
\r
16 * intellectual property rights. NXP Semiconductors assumes no responsibility
\r
17 * or liability for the use of the software, conveys no license or rights under any
\r
18 * patent, copyright, mask work right, or any other intellectual property rights in
\r
19 * or to any products. NXP Semiconductors reserves the right to make changes
\r
20 * in the software without notification. NXP Semiconductors also makes no
\r
21 * representation or warranty that such application will be suitable for the
\r
22 * specified use without further testing or modification.
\r
25 * Permission to use, copy, modify, and distribute this software and its
\r
26 * documentation is hereby granted, under NXP Semiconductors' and its
\r
27 * licensor's relevant copyrights in the software, without fee, provided that it
\r
28 * is used in conjunction with NXP Semiconductors microcontrollers. This
\r
29 * copyright, permission, and disclaimer notice must appear in all copies of
\r
33 /** @ingroup Group_USB
\r
34 * @defgroup Group_Events USB Events
\r
35 * @brief USB Event management definitions.
\r
37 * This module contains macros and functions relating to the management of library events, which are small
\r
38 * pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from
\r
39 * multiple places in the user or library code, which may or may not be inside an ISR, thus each handler
\r
40 * should be written to be as small and fast as possible to prevent possible problems.
\r
42 * Events can be hooked by the user application by declaring a handler function with the same name and parameters
\r
43 * listed here. If an event with no user-associated handler is fired within the library, it by default maps to an
\r
44 * internal empty stub function.
\r
46 * Each event must only have one associated event handler, but can be raised by multiple sources by calling the
\r
47 * event handler function (with any required event parameters).
\r
52 #ifndef __USBEVENTS_H__
\r
53 #define __USBEVENTS_H__
\r
56 #include "../../../Common/Common.h"
\r
57 #include "USBMode.h"
\r
59 /* Enable C linkage for C++ Compilers: */
\r
60 #if defined(__cplusplus)
\r
64 /* Preprocessor Checks: */
\r
65 #if !defined(__INCLUDE_FROM_USB_DRIVER)
\r
66 #error Do not include this file directly. Include lpcroot/libraries/LPCUSBlib/Drivers/USB/USB.h instead.
\r
69 /* Public Interface - May be used in end-application: */
\r
70 /* Pseudo-Functions for Doxygen: */
\r
71 #if !defined(__INCLUDE_FROM_EVENTS_C) || defined(__DOXYGEN__)
\r
72 /** Event for USB mode pin level change. This event fires when the USB interface is set to dual role
\r
73 * mode, and the UID pin level has changed to indicate a new mode (device or host). This event fires
\r
74 * before the mode is switched to the newly indicated mode but after the @ref EVENT_USB_Device_Disconnect
\r
75 * event has fired (if disconnected before the role change).
\r
77 * @note This event only exists on microcontrollers that support dual role USB modes.
\r
80 * @note This event does not exist if the \c USB_DEVICE_ONLY or \c USB_HOST_ONLY tokens have been supplied
\r
81 * to the compiler (see @ref Group_USBManagement documentation).
\r
83 void EVENT_USB_UIDChange(void);
\r
85 /** Event for USB host error. This event fires when a hardware fault has occurred whilst the USB
\r
86 * interface is in host mode.
\r
88 * @param corenum : USB port number
\r
89 * @param ErrorCode : Error code indicating the failure reason, a value in @ref USB_Host_ErrorCodes_t.
\r
91 * @note This event only exists on microcontrollers that supports USB host mode.
\r
94 * @note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
\r
95 * @ref Group_USBManagement documentation).
\r
97 void EVENT_USB_Host_HostError(const uint8_t corenum, const uint8_t ErrorCode);
\r
99 /** Event for USB device attachment. This event fires when a the USB interface is in host mode, and
\r
100 * a USB device has been connected to the USB interface. This is interrupt driven, thus fires before
\r
101 * the standard @ref EVENT_USB_Device_Connect() event and so can be used to programmatically start the USB
\r
102 * management task to reduce CPU consumption.
\r
104 * @note This event only exists on microcontrollers that supports USB host mode.
\r
107 * @note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
\r
108 * @ref Group_USBManagement documentation).
\r
110 * @see @ref USB_USBTask() for more information on the USB management task and reducing CPU usage.
\r
112 void EVENT_USB_Host_DeviceAttached(const uint8_t corenum);
\r
114 /** Event for USB device removal. This event fires when a the USB interface is in host mode, and
\r
115 * a USB device has been removed the USB interface whether or not it has been enumerated. This
\r
116 * can be used to programmatically stop the USB management task to reduce CPU consumption.
\r
118 * @note This event only exists on microcontrollers that supports USB host mode.
\r
121 * @note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
\r
122 * @ref Group_USBManagement documentation).
\r
124 * @see @ref USB_USBTask() for more information on the USB management task and reducing CPU usage.
\r
126 void EVENT_USB_Host_DeviceUnattached(const uint8_t corenum);
\r
128 /** Event for USB device enumeration failure. This event fires when a the USB interface is
\r
129 * in host mode, and an attached USB device has failed to enumerate completely.
\r
131 * @param corenum : USB port number
\r
133 * @param ErrorCode Error code indicating the failure reason, a value in
\r
134 * @ref USB_Host_EnumerationErrorCodes_t.
\r
136 * @param SubErrorCode Sub error code indicating the reason for failure - for example, if the
\r
137 * ErrorCode parameter indicates a control error, this will give the error
\r
138 * code returned by the @ref USB_Host_SendControlRequest() function.
\r
140 * @note This event only exists on microcontrollers that supports USB host mode.
\r
143 * @note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
\r
144 * @ref Group_USBManagement documentation).
\r
146 void EVENT_USB_Host_DeviceEnumerationFailed(const uint8_t corenum,
\r
147 const uint8_t ErrorCode,
\r
148 const uint8_t SubErrorCode);
\r
150 /** Event for USB device enumeration completion. This event fires when a the USB interface is
\r
151 * in host mode and an attached USB device has been completely enumerated and is ready to be
\r
152 * controlled by the user application.
\r
154 * This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
\r
155 * 1 second) when a transaction is waiting to be processed by the device will prevent break communications
\r
156 * and cause the host to reset the USB bus.
\r
158 void EVENT_USB_Host_DeviceEnumerationComplete(const uint8_t corenum);
\r
160 /** Event for USB Start Of Frame detection, when enabled. This event fires at the start of each USB
\r
161 * frame, once per millisecond, and is synchronized to the USB bus. This can be used as an accurate
\r
162 * millisecond timer source when the USB bus is not suspended while in host mode.
\r
164 * This event is time-critical; it is run once per millisecond and thus long handlers will significantly
\r
165 * degrade device performance. This event should only be enabled when needed to reduce device wake-ups.
\r
167 * @note This event is not normally active - it must be manually enabled and disabled via the
\r
168 * @ref USB_Host_EnableSOFEvents() and @ref USB_Host_DisableSOFEvents() commands after enumeration of
\r
172 * @note This event does not exist if the \c USB_DEVICE_ONLY token is supplied to the compiler (see
\r
173 * @ref Group_USBManagement documentation).
\r
175 void EVENT_USB_Host_StartOfFrame(const uint8_t corenum);
\r
177 /** Event for USB device connection. This event fires when the microcontroller is in USB Device mode
\r
178 * and the device is connected to a USB host, beginning the enumeration process measured by a rising
\r
179 * level on the microcontroller's VBUS sense pin.
\r
181 * This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
\r
182 * two seconds) will prevent the device from enumerating correctly.
\r
184 * @note For the microcontrollers with limited USB controller functionality, VBUS sensing is not available.
\r
185 * this means that the current connection state is derived from the bus suspension and wake up events by default,
\r
186 * which is not always accurate (host may suspend the bus while still connected). If the actual connection state
\r
187 * needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
\r
188 * passing the \c NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
\r
189 * and disconnection events may be manually fired, and the @ref USB_DeviceState global changed manually.
\r
192 * @note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
\r
193 * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
\r
195 * @see @ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
\r
197 void EVENT_USB_Device_Connect(void);
\r
199 /** Event for USB device disconnection. This event fires when the microcontroller is in USB Device mode and the device is
\r
200 * disconnected from a host, measured by a falling level on the microcontroller's VBUS sense pin.
\r
202 * @note For the microcontrollers with limited USB controllers, VBUS sense is not available to the USB controller.
\r
203 * this means that the current connection state is derived from the bus suspension and wake up events by default,
\r
204 * which is not always accurate (host may suspend the bus while still connected). If the actual connection state
\r
205 * needs to be determined, VBUS should be routed to an external pin, and the auto-detect behaviour turned off by
\r
206 * passing the \c NO_LIMITED_CONTROLLER_CONNECT token to the compiler via the -D switch at compile time. The connection
\r
207 * and disconnection events may be manually fired, and the @ref USB_DeviceState global changed manually.
\r
210 * @note This event may fire multiple times during device enumeration on the microcontrollers with limited USB controllers
\r
211 * if \c NO_LIMITED_CONTROLLER_CONNECT is not defined.
\r
213 * @see @ref Group_USBManagement for more information on the USB management task and reducing CPU usage.
\r
215 void EVENT_USB_Device_Disconnect(void);
\r
217 /** Event for control requests. This event fires when a the USB host issues a control request
\r
218 * to the mandatory device control endpoint (of address 0). This may either be a standard
\r
219 * request that the library may have a handler code for internally, or a class specific request
\r
220 * issued to the device which must be handled appropriately. If a request is not processed in the
\r
221 * user application via this event, it will be passed to the library for processing internally
\r
222 * if a suitable handler exists.
\r
224 * This event is time-critical; each packet within the request transaction must be acknowledged or
\r
225 * sent within 50ms or the host will abort the transfer.
\r
227 * The library internally handles all standard control requests with the exceptions of SYNC FRAME,
\r
228 * SET DESCRIPTOR and SET INTERFACE. These and all other non-standard control requests will be left
\r
229 * for the user to process via this event if desired. If not handled in the user application or by
\r
230 * the library internally, unknown requests are automatically STALLed.
\r
232 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
233 * @ref Group_USBManagement documentation).
\r
236 * @note Requests should be handled in the same manner as described in the USB 2.0 Specification,
\r
237 * or appropriate class specification. In all instances, the library has already read the
\r
238 * request SETUP parameters into the @ref USB_ControlRequest structure which should then be used
\r
239 * by the application to determine how to handle the issued request.
\r
241 void EVENT_USB_Device_ControlRequest(void);
\r
243 /** Event for USB configuration number changed. This event fires when a the USB host changes the
\r
244 * selected configuration number while in device mode. This event should be hooked in device
\r
245 * applications to create the endpoints and configure the device for the selected configuration.
\r
247 * This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
\r
248 * one second) will prevent the device from enumerating correctly.
\r
250 * This event fires after the value of @ref USB_Device_ConfigurationNumber has been changed.
\r
252 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
253 * @ref Group_USBManagement documentation).
\r
255 void EVENT_USB_Device_ConfigurationChanged(void);
\r
257 /** Event for USB suspend. This event fires when a the USB host suspends the device by halting its
\r
258 * transmission of Start Of Frame pulses to the device. This is generally hooked in order to move
\r
259 * the device over to a low power state until the host wakes up the device. If the USB interface is
\r
260 * enumerated with the @ref USB_OPT_AUTO_PLL option set, the library will automatically suspend the
\r
261 * USB PLL before the event is fired to save power.
\r
263 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
264 * @ref Group_USBManagement documentation).
\r
267 * @note This event does not exist on the microcontrollers with limited USB VBUS sensing abilities
\r
268 * when the \c NO_LIMITED_CONTROLLER_CONNECT compile time token is not set - see
\r
269 * @ref EVENT_USB_Device_Disconnect.
\r
271 * @see @ref EVENT_USB_Device_WakeUp() event for accompanying Wake Up event.
\r
273 void EVENT_USB_Device_Suspend(void);
\r
275 /** Event for USB wake up. This event fires when a the USB interface is suspended while in device
\r
276 * mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally
\r
277 * hooked to pull the user application out of a low power state and back into normal operating
\r
278 * mode. If the USB interface is enumerated with the @ref USB_OPT_AUTO_PLL option set, the library
\r
279 * will automatically restart the USB PLL before the event is fired.
\r
281 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
282 * @ref Group_USBManagement documentation).
\r
285 * @note This event does not exist on the microcontrollers with limited USB VBUS sensing abilities
\r
286 * when the \c NO_LIMITED_CONTROLLER_CONNECT compile time token is not set - see
\r
287 * @ref EVENT_USB_Device_Disconnect.
\r
289 * @see @ref EVENT_USB_Device_Suspend() event for accompanying Suspend event.
\r
291 void EVENT_USB_Device_WakeUp(void);
\r
293 /** Event for USB interface reset. This event fires when the USB interface is in device mode, and
\r
294 * a the USB host requests that the device reset its interface. This event fires after the control
\r
295 * endpoint has been automatically configured by the library.
\r
297 * This event is time-critical; exceeding OS-specific delays within this event handler (typically of around
\r
298 * two seconds) will prevent the device from enumerating correctly.
\r
300 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
301 * @ref Group_USBManagement documentation).
\r
303 void EVENT_USB_Device_Reset(void);
\r
305 /** Event for USB Start Of Frame detection, when enabled. This event fires at the start of each USB
\r
306 * frame, once per millisecond, and is synchronized to the USB bus. This can be used as an accurate
\r
307 * millisecond timer source when the USB bus is enumerated in device mode to a USB host.
\r
309 * This event is time-critical; it is run once per millisecond and thus long handlers will significantly
\r
310 * degrade device performance. This event should only be enabled when needed to reduce device wake-ups.
\r
312 * \pre This event is not normally active - it must be manually enabled and disabled via the
\r
313 * @ref USB_Device_EnableSOFEvents() and @ref USB_Device_DisableSOFEvents() commands after enumeration.
\r
316 * @note This event does not exist if the \c USB_HOST_ONLY token is supplied to the compiler (see
\r
317 * @ref Group_USBManagement documentation).
\r
319 void EVENT_USB_Device_StartOfFrame(void);
\r
322 /* Private Interface - For use in library only: */
\r
323 #if !defined(__DOXYGEN__)
\r
324 /* Function Prototypes: */
\r
325 #if defined(__INCLUDE_FROM_EVENTS_C)
\r
326 void USB_Event_Stub(void) ATTR_CONST;
\r
327 #if defined(__ICCARM__)
\r
328 void USB_Host_HostError_Event_Stub(const uint8_t ErrorCode);
\r
329 void USB_Host_DeviceEnumerationFailed_Event_Stub(const uint8_t ErrorCode,
\r
330 const uint8_t SubErrorCode);
\r
332 #if defined(USB_CAN_BE_BOTH)
\r
333 PRAGMA_WEAK(EVENT_USB_UIDChange,USB_Event_Stub)
\r
334 void EVENT_USB_UIDChange(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
337 #if defined(USB_CAN_BE_HOST)
\r
338 PRAGMA_WEAK(EVENT_USB_Host_HostError,USB_Event_Stub)
\r
339 #if !defined(__ICCARM__)
\r
340 void EVENT_USB_Host_HostError(const uint8_t ErrorCode) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
342 PRAGMA_WEAK(EVENT_USB_Host_DeviceAttached,USB_Event_Stub)
\r
343 void EVENT_USB_Host_DeviceAttached(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
344 PRAGMA_WEAK(EVENT_USB_Host_DeviceUnattached,USB_Event_Stub)
\r
345 void EVENT_USB_Host_DeviceUnattached(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
346 PRAGMA_WEAK(EVENT_USB_Host_DeviceEnumerationComplete,USB_Event_Stub)
\r
347 void EVENT_USB_Host_DeviceEnumerationComplete(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
348 PRAGMA_WEAK(EVENT_USB_Host_DeviceEnumerationFailed,USB_Event_Stub)
\r
349 #if !defined(__ICCARM__)
\r
350 void EVENT_USB_Host_DeviceEnumerationFailed(const uint8_t ErrorCode,
\r
351 const uint8_t SubErrorCode)
\r
352 ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
354 PRAGMA_WEAK(EVENT_USB_Host_StartOfFrame,USB_Event_Stub)
\r
355 void EVENT_USB_Host_StartOfFrame(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
358 #if defined(USB_CAN_BE_DEVICE)
\r
359 PRAGMA_WEAK(EVENT_USB_Device_Connect,USB_Event_Stub)
\r
360 void EVENT_USB_Device_Connect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
361 PRAGMA_WEAK(EVENT_USB_Device_Disconnect,USB_Event_Stub)
\r
362 void EVENT_USB_Device_Disconnect(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
363 PRAGMA_WEAK(EVENT_USB_Device_ControlRequest,USB_Event_Stub)
\r
364 void EVENT_USB_Device_ControlRequest(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
365 PRAGMA_WEAK(EVENT_USB_Device_ConfigurationChanged,USB_Event_Stub)
\r
366 void EVENT_USB_Device_ConfigurationChanged(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
367 PRAGMA_WEAK(EVENT_USB_Device_Suspend,USB_Event_Stub)
\r
368 void EVENT_USB_Device_Suspend(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
369 PRAGMA_WEAK(EVENT_USB_Device_WakeUp,USB_Event_Stub)
\r
370 void EVENT_USB_Device_WakeUp(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
371 PRAGMA_WEAK(EVENT_USB_Device_Reset,USB_Event_Stub)
\r
372 void EVENT_USB_Device_Reset(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
373 PRAGMA_WEAK(EVENT_USB_Device_StartOfFrame,USB_Event_Stub)
\r
374 void EVENT_USB_Device_StartOfFrame(void) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub);
\r
379 /* Disable C linkage for C++ Compilers: */
\r
380 #if defined(__cplusplus)
\r
projects / freertos / blob