2.2.2.3.3 Event Handling
The Device Layer generates events to let the application client know about the state of the bus. Some of these events require the application to respond in a specific manner. Not doing so, could cause the USB device to malfunction and become non-compliant. Code inside the event handler executes in an interrupt context when the Device Layer (unless otherwise noted). The application must avoid calling computationally intensive functions or blocking functions in the event handler. The application can call interrupt safe functions in the event handler.
The following table shows a summary of the events that the Device Layer generates and the required application client response.
| Event | Required Application Response |
| USB_DEVICE_EVENT_POWER_DETECTED | Attach the device. |
| USB_DEVICE_EVENT_POWER_REMOVED | Detach the device. |
| USB_DEVICE_EVENT_RESET | No response required. |
| USB_DEVICE_EVENT_SUSPENDED | No response required. |
| USB_DEVICE_EVENT_RESUMED | No response required. |
| USB_DEVICE_EVENT_ERROR | The application can try detaching the device and reattaching. This should be done after exiting from the event handler. |
| USB_DEVICE_EVENT_SOF | No response required. |
| USB_DEVICE_EVENT_CONFIGURED | The application must check the configuration that was activated and register event handlers with all function drivers that are contained in the activated configuration. |
| USB_DEVICE_EVENT_DECONFIGURED | No response required. |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST | Application must either respond with a USB_DEVICE_ControlSend() to send data, USB_DEVICE_ControlReceive() to receive data or stall or acknowledge the control request by calling the USB_DEVICE_ControlStatus() function. |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT | No response required. |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED | Application must either or stall or acknowledge the control request by calling the USB_DEVICE_ControlStatus() function. |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_ABORTED | No response required. |
The Device Layer generates events with event specific data. The pData parameter in the event handler functions points to this event specific data. The application can access this data by type casting the pData parameter of the event handler function to a event specific data type. The following table shows a summary of the USB Device Layer events and the event data generated along with the event.
| Event | Related pData Type |
| USB_DEVICE_EVENT_POWER_DETECTED | NULL |
| USB_DEVICE_EVENT_POWER_REMOVED | NULL |
| USB_DEVICE_EVENT_RESET | NULL |
| USB_DEVICE_EVENT_SUSPENDED | NULL |
| USB_DEVICE_EVENT_RESUMED | NULL |
| USB_DEVICE_EVENT_ERROR | NULL |
| USB_DEVICE_EVENT_SOF | USB_DEVICE_EVENT_DATA_SOF * |
| USB_DEVICE_EVENT_CONFIGURED | USB_DEVICE_EVENT_DATA_CONFIGURED* |
| USB_DEVICE_EVENT_DECONFIGURED | NULL |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST | USB_SETUP_PACKET * |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT | NULL |
| USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED | NULL |
A detailed description of each Device Layer event along with the required application client response, the likely follow-up event (if applicable) and the event specific data is provided here.
USB_DEVICE_EVENT_POWER_DETECTED
Application Response: This event indicates that the device has detected a valid VBUS to the host. The device is yet to be enumerated and configured. The application should not access the function drivers at this point. The application can use this event to attach the device on the bus.
Event Specific Data(pData): The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_POWER_REMOVED
Application Response: This event is an indication to the application client that the device is detached from the bus. The application can use this event to detach the device.
Event Specific Data(pData): The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_SUSPENDED
Application Response: This event is an indication to the application client that device is suspended and it can put the device to sleep mode if required. Power saving routines should not be called in the event handler.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_RESET
Application Response: USB bus reset occurred. This event is an indication to the application client that device layer has deinitialized all function drivers. The application should not use the function drivers in this state.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_RESUMED
Application Response: This event indicates that device has resumed from suspended state. The application can use this event to resume the operational state of the device.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_ERROR
Application Response: This event is an indication to the application client that an error occurred on the USB bus. The application can try detaching and reattaching the device.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_EVENT_SOF
Application Response: This event occurs when the device receives a Start Of Frame packet. The application can use this event for synchronizing purposes. This event will be received every 1 millisecond for Full Speed USB and every one 125 micro seconds for High Speed USB. No application response is required.
Event Specific Data: Will point to USB_DEVICE_EVENT_DATA_SOF data type containing the frame number.
Likely Follow Up Event: None.
USB_DEVICE_CONFIGURED
Application Response: This event is an indication to the application client that device layer has initialized all function drivers. The application can check the configuration set by the host. The application should use the event to register event handlers with the function drivers that are contained in the active configuration.
Event Specific Data: The pData parameter will point to a USB_DEVICE_EVENT_DATA_CONFIGURED data type that contains the configuration set by the host.
Likely Follow Up Event: None.
USB_DEVICE_DECONFIGURED
Application Response: The host has deconfigured the device. This happens when the host sends a Set Configuration request with configuration number 0. The device layer will deinitialize all function drivers and then generate this event. No application response is required.
Event Specific Data:: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_CONTROL_TRANSFER_ABORTED
Application Response: An on-going control transfer was aborted. The application can use this event to reset it's control transfer state machine.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_CONTROL_TRANSFER_DATA_RECEIVED
Application Response: The data stage of a Control write transfer has completed. This event occurs after the application has used the USB_DEVICE_ControlReceive() function to receive data in the control transfer (in response to the USB_DEVICE_CONTROL_TRANSFER_SETUP_REQUEST event) . The application can inspect the received data and stall or acknowledge the control transfer by calling the USB_DEVICE_ControlStatus() function with the USB_DEVICE_CONTROL_STATUS_ERROR flag or USB_DEVICE_CONTROL_STATUS_OK flag respectively. The application can call the USB_DEVICE_ControlStatus() function in the event handler or after exiting the event handler.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
USB_DEVICE_CONTROL_TRANSFER_SETUP_REQUEST
Application Response: A setup packet of a control transfer has been received. The recipient field of the received setup packet is Other. The application can initiate the data stage by using the USB_DEVICE_ControlReceive() and USB_DEVICE_ControlSend() functions. It can end the control transfer by calling the USB_DEVICE_ControlStatus() function. The application will recieve this event when the Control Transfer recipient field is set to Other.
Event Specific Data: The pData parameter in the event handler will point to USB_SETUP_PACKET data type.
Likely Follow Up Event: USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT if the USB_DEVICE_ControlSend() function was called to send data to the host. USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED if the USB_DEVICE_ControlReceive() function was called to receive data from the host.
USB_DEVICE_CONTROL_TRANSFER_DATA_SENT
Application Response: The data stage of a Control Read transfer has completed. This event occurs after the application has used the USB_DEVICE_ControlSend() function to send data in the control transfer. No application response is required.
Event Specific Data: The pData parameter will be NULL.
Likely Follow Up Event: None.
Topics
| Name | Description |
| Device Layer Control Transfers | Describes the operation of USB Device Layer control transfers. |