2.5.4.10 USB_DEVICE_CDC_EVENT Enumeration

C

typedef enum {
  USB_DEVICE_CDC_EVENT_SET_LINE_CODING,
  USB_DEVICE_CDC_EVENT_GET_LINE_CODING,
  USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE,
  USB_DEVICE_CDC_EVENT_SEND_BREAK,
  USB_DEVICE_CDC_EVENT_WRITE_COMPLETE,
  USB_DEVICE_CDC_EVENT_READ_COMPLETE,
  USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE,
  USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT,
  USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED,
  USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_ABORTED
} USB_DEVICE_CDC_EVENT;

Description

USB Device CDC Function Driver Events

These events are specific to the USB Device CDC Function Driver instance. Each event description contains details about the parameters passed with event. The contents of pData depends on the generated event.

Events associated with the CDC Function Driver Specific Control Transfers require application response. The application should respond to these events by using the USB_DEVICE_ControlReceive, USB_DEVICE_ControlSend and USB_DEVICE_ControlStatus functions.

Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR will stall the control transfer request. The application would do this if the control transfer request is not supported. Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK will complete the status stage of the control transfer request. The application would do this if the control transfer request is supported.

The following code snippet shows an example of a possible event handling scheme.

// This code example shows all CDC Function Driver events 
// and a possible scheme for handling these events. In this example
// event responses are not deferred. usbDeviceHandle is obtained while
// opening the USB Device Layer through the USB_DEVICE_Open function.

uint16_t * breakData;
USB_DEVICE_HANDLE    usbDeviceHandle;
USB_CDC_LINE_CODING  lineCoding;
USB_CDC_CONTROL_LINE_STATE * controlLineStateData;

USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler
(
    USB_DEVICE_CDC_INDEX instanceIndex, 
    USB_DEVICE_CDC_EVENT event, 
    void * pData,
    uintptr_t userData
)
{
    switch(event)
    {
        case USB_DEVICE_CDC_EVENT_SET_LINE_CODING:

            // In this case, the application should read the line coding
            // data that is sent by the host. The application must use the
            // USB_DEVICE_ControlReceive function to receive the 
            // USB_CDC_LINE_CODING type of data.
            
            USB_DEVICE_ControlReceive(usbDeviceHandle, &lineCoding, sizeof(USB_CDC_LINE_CODING));
            break;

        case USB_DEVICE_CDC_EVENT_GET_LINE_CODING:

            // In this case, the application should send the line coding
            // data to the host. The application must send the 
            // USB_DEVICE_ControlSend function to send the data. 

            USB_DEVICE_ControlSend(usbDeviceHandle, &lineCoding, sizeof(USB_CDC_LINE_CODING));
            break;

        case USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE:
            
            // In this case, pData should be interpreted as a
            // USB_CDC_CONTROL_LINE_STATE pointer type.  The application
            // acknowledges the parameters by calling the
            // USB_DEVICE_ControlStatus function with the
            // USB_DEVICE_CONTROL_STATUS_OK option.
         
            controlLineStateData = (USB_CDC_CONTROL_LINE_STATE *)pData;
            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);   
            break;

        case USB_DEVICE_CDC_EVENT_SEND_BREAK:
           
            // In this case, pData should be interpreted as a uint16_t
            // pointer type to the break duration. The application
            // acknowledges the parameters by calling the
            // USB_DEVICE_ControlStatus() function with the
            // USB_DEVICE_CONTROL_STATUS_OK option.
            
            breakDuration = (uint16_t *)pData; 
            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT:

            // This event indicates the data send request associated with
            // the latest USB_DEVICE_ControlSend function was
            // completed.  The application could use this event to track
            // the completion of the USB_DEVICE_CDC_EVENT_GET_LINE_CODING
            // request. 

            break;

        case USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // This event indicates the data that was requested using the
            // USB_DEVICE_ControlReceive function is available for the
            // application to peruse. The application could use this event
            // to track the completion of the
            // USB_DEVICE_CDC_EVENT_SET_LINE_CODING_EVENT event. The
            // application can then either accept the line coding data (as
            // shown here) or decline it by using the
            // USB_DEVICE_CONTROL_STATUS_ERROR flag in the
            // USB_DEVICE_ControlStatus function.
            
            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;
        
        case USB_DEVICE_CDC_EVENT_WRITE_COMPLETE:
            
            // This event indicates that a CDC Write Transfer request has
            // completed.  pData should be interpreted as a 
            // USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE pointer type. This
            // contains the transfer handle of the write transfer that
            // completed and amount of data that was written.

            break;

        case USB_DEVICE_CDC_EVENT_READ_COMPLETE:
            
            // This event indicates that a CDC Read Transfer request has
            // completed.  pData should be interpreted as a 
            // USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE pointer type. This
            // contains the transfer handle of the read transfer that
            // completed and amount of data that was written.
       
            break;
        
        case USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE:

            // This event indicates that a CDC Serial State Notification
            // Send request has completed. pData should be interpreted as a
            // USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE
            // pointer type. This will contain the transfer handle
            // associated with the send request and the amount of data that
            // was sent.     

        break

         default:
            break;
     }

    return(USB_DEVICE_CDC_EVENT_RESPONSE_NONE);
}

Members

Remarks

The USB Device CDC control transfer related events allow the application to defer responses. This allows the application some time to obtain the response data rather than having to respond to the event immediately. Note that a USB host will typically wait for event response for a finite time duration before timing out and canceling the event and associated transactions. Even when deferring response, the application must respond promptly if such time outs have to be avoided.