Jump to main content

##

# 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.