2.2.4.32 USB_DEVICE_EVENT Enumeration

C

typedef enum {
  USB_DEVICE_EVENT_RESET,
  USB_DEVICE_EVENT_SUSPENDED,
  USB_DEVICE_EVENT_RESUMED,
  USB_DEVICE_EVENT_ERROR,
  USB_DEVICE_EVENT_SOF,
  USB_DEVICE_EVENT_CONFIGURED,
  USB_DEVICE_EVENT_DECONFIGURED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT,
  USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE,
  USB_DEVICE_EVENT_ENDPOINT_WRITE_COMPLETE,
  USB_DEVICE_EVENT_SET_DESCRIPTOR,
  USB_DEVICE_EVENT_SYNCH_FRAME
} USB_DEVICE_EVENT;

Description

USB Device Layer Events.

This enumeration lists the possible events that the device layer can generate. The client should register an event handler of the type USB_DEVICE_EVENT_HANDLER to receive device layer events. The contents of pData in the event handler depends on the generated event. Refer to the description of the event for details on data provided along with that event. The events generated are device layer instance specific.

The client will receive control transfers for handling from the device layer, where the recipient field of the Control Transfer Setup packet is set to Other. The client can use the control transfer events and the Device Layer control transfer functions to complete such control transfers.

It is not mandatory for the client application to handle the control transfer event within the event handler. Indeed, it may be possible that the data stage of the control transfer requires extended processing. Because the event handler executes in an interrupt context, it is recommended to keep the processing in the event handler to a minimum. The client application can call the USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive and USB_DEVICE_ControlStatus functions after returning from the event handler, thus deferring the control transfer event handling and responses.

Note that a USB host will typically wait for control transfer response for a finite time duration before timing out and canceling the transfer and associated transactions. Even when deferring response, the application must respond promptly if such timeouts have to be avoided.

The client must use the USB_DEVICE_EventHandlerSet function to register the event handler call back function. The following code example shows the handling of the USB Device Layer Events.

USB_DEVICE_EVENT_RESPONSE APP_USBDeviceEventHandler
(
    USB_DEVICE_EVENT event,
    void * pData, 
    uintptr_t context
)
{
    uint8_t     activeConfiguration;
    uint16_t    frameNumber;
    USB_SPEED   attachSpeed;
    USB_SETUP_PACKET * setupEventData;

    // Handling of each event
    switch(event)
    {
        case USB_DEVICE_EVENT_POWER_DETECTED:
            
            // This means the device detected a valid VBUS voltage and is
            // attached to the USB. The application can now call
            // USB_DEVICE_Attach() function to enable D+/D- pull up
            // resistors. 
            break;

        case USB_DEVICE_EVENT_POWER_REMOVED:
            
            // This means the device is not attached to the USB.
            // The application should now call the USB_DEVICE_Detach()
            // function.
            break;

        case USB_DEVICE_EVENT_SUSPENDED:
            
            // The bus is idle. There was no activity detected.
            // The application can switch to a low power mode after
            // exiting the event handler.
            break;

        case USB_DEVICE_EVENT_SOF:

            // A start of frame was received. This is a periodic event and
            // can be used by the application for timing related activities.
            // pData will point to a USB_DEVICE_EVENT_DATA_SOF type data
            // containing the frame number. In USB Device Stack, this
            // event is generated if USB_DEVICE_SOF_EVENT_ENABLE is
            // defined in System Configuration.

            frameNumber = ((USB_DEVICE_EVENT_DATA_SOF *)pData)->frameNumber;
            break;

        case USB_DEVICE_EVENT_RESET :

            // Reset signaling was detected on the bus. The 
            // application can find out the attach speed.
            
            attachSpeed = USB_DEVICE_ActiveSpeedGet(usbDeviceHandle);
            break;

        case USB_DEVICE_EVENT_DECONFIGURED :
            
            // This indicates that host has deconfigured the device i.e., it
            // has set the configuration as 0. All function driver instances
            // would have been deinitialized.
            
            break;

        case USB_DEVICE_EVENT_ERROR :

            // This means an unknown error has occurred on the bus.
            // The application can try detaching and attaching the
            // device again.
            break;

        case USB_DEVICE_EVENT_CONFIGURED :

            // This means that device is configured and the application can
            // start using the device functionality. The application must
            // register function driver event handlersI have one device
            // level event.  The pData parameter will be a pointer to a
            // USB_DEVICE_EVENT_DATA_CONFIGURED data type that contains the
            // active configuration number.

            activeConfiguration = ((USB_DEVICE_EVENT_DATA_CONFIGURED *)pData)->configurationValue;
            break;
            
        case USB_DEVICE_EVENT_RESUMED:

            // This means that the resume signaling was detected on the
            // bus. The application can bring the device out of power
            // saving mode.

            break;
        
        case USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST:

            // This means that the setup stage of the control transfer is in
            // progress and a setup packet has been received. The pData
            // parameter will point to a USB_SETUP_PACKET data type The
            // application can process the command and update its control
            // transfer state machine. The application for example could call
            // the USB_DEVICE_ControlReceive function (as shown here) to
            // submit the buffer that would receive data in case of a
            // control read transfer.

            setupEventData = (USB_SETUP_PACKET *)pData;

            // Submit a buffer to receive 32 bytes in the  control write transfer.
            USB_DEVICE_ControlReceive(usbDeviceHandle, data, 32); 
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // This means that data in the data stage of the control write
            // transfer has been received. The application can either accept
            // the received data by calling the USB_DEVICE_ControlStatus
            // function with USB_DEVICE_CONTROL_STATUS_OK flag (as shown in
            // this example) or it can reject it by calling the
            // USB_DEVICE_ControlStatus function with
            // USB_DEVICE_CONTROL_STATUS_ERROR flag. 

            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT:
            
            // This means that data in the data stage of the control
            // read transfer has been sent. 

            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED:

            // This means the host has aborted the control transfer. The
            // application can reset its control transfer state machine.
            
            break;

        case USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE:

            // This means schedule endpoint read operation has completed.
            // The application should interpret pData as a pointer to 
            // a USB_DEVICE_EVENT_DATA_ENDPOINT_READ_COMPLETE type.
            
            break;
        
        case USB_DEVICE_EVENT_ENDPOINT_WRITE_COMPLETE:

            // This means schedule endpoint write operation has completed.
            // The application should interpret pData as a pointer to 
            // a USB_DEVICE_EVENT_DATA_ENDPOINT_WRITE_COMPLETE type.
            
            break;

        case USB_DEVICE_EVENT_SET_DESCRIPTOR:
            
            // This means the Host has sent a Set Descriptor request. The
            // application should interpret pData as a
            // USB_DEVICE_EVENT_DATA_SET_DESCRIPTOR pointer type containing the
            // details of the Set Descriptor request. In USB Device
            // Stack, this event is generated if 
            // USB_DEVICE_SET_DESCRIPTOR_EVENT_ENABLE is defined in the
            // system configuration. The application can use
            // USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive and/or
            // the USB_DEVICE_ControlStatus functions to complete the
            // control transfer.

            break;

        case USB_DEVICE_EVENT_SYNCH_FRAME:

            // This means the host has sent a Sync Frame Request. The
            // application should interpret pData as a
            // USB_DEVICE_EVENT_DATA_SYNCH_FRAME pointer type. In USB Device
            // Stack, this event is generated if 
            // USB_DEVICE_SYNCH_FRAME_EVENT_ENABLE is defined in the
            // system configuration. The application should respond be
            // sending the 2 byte frame number using the
            // USB_DEVICE_ControlSend function. 

            USB_DEVICE_ControlSend(usbDeviceHandle, &frameNumber, 2);
            break;

        default:
            break;
    }

    return USB_DEVICE_EVENT_RESPONSE_NONE;
}

Members

Remarks

Generation of some events required the definition of configuration macros. Refer to the event specific description for more details.