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

Members Description
USB_DEVICE_CDC_EVENT_SET_LINE_CODING This event occurs when the host issues a SET LINE CODING command. The application must provide a USB_CDC_LINE_CODING data structure to the device layer to receive the line coding data that the host will provide. The application must provide the buffer by calling the USB_DEVICE_ControlReceive function either in the event handler or in the application, after returning from the event handler function. The pData parameter will be NULL. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event to track completion of the command.
USB_DEVICE_CDC_EVENT_GET_LINE_CODING This event occurs when the host issues a GET LINE CODING command. The application must provide a USB_CDC_LINE_CODING data structure to the device layer that contains the line coding data to be provided to the host. The application must provide the buffer by calling the USB_DEVICE_ControlSend function either in the event handler or in the application, after returning from the event handler function. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command.
USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE This event occurs when the host issues a SET CONTROL LINE STATE command. The application must interpret the pData parameter as USB_CDC_CONTROL_LINE_STATE pointer type. This data structure contains the control line state data. The application can then use the USB_DEVICE_ControlStatus function to indicate acceptance or rejection of the command. The USB_DEVICE_ControlStatus function can be called from the event handler or in the application, after returning from the event handler.
USB_DEVICE_CDC_EVENT_SEND_BREAK This event occurs when the host issues a SEND BREAK command. The application must interpret the pData parameter as a USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK pointer type. This data structure contains the break duration data. The application can then use the USB_DEVICE_ControlStatus function to indicate acceptance of rejection of the command. The USB_DEVICE_ControlStatus function can be called from the event handler or in the application, after returning from the event handler.
USB_DEVICE_CDC_EVENT_WRITE_COMPLETE This event occurs when a write operation scheduled by calling the USB_DEVICE_CDC_Write function has completed. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE pointer type. This will contain the transfer handle associated with the completed write transfer and the amount of data written.
USB_DEVICE_CDC_EVENT_READ_COMPLETE This event occurs when a read operation scheduled by calling the USB_DEVICE_CDC_Read function has completed. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE pointer type. This will contain the transfer handle associated with the completed read transfer and the amount of data read.
USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE This event occurs when a serial state notification scheduled using the USB_DEVICE_CDC_SerialStateNotificationSend function, was sent to the host. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE pointer type and will contain the transfer handle associated with the completed send transfer and the amount of data sent.
USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT This event occurs when the data stage of a control read transfer has completed. This event would occur after the application uses the USB_DEVICE_ControlSend function to respond to the USB_DEVICE_CDC_EVENT_GET_LINE_CODING event.
USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED This event occurs when the data stage of a control write transfer has completed. This would occur after the application would respond with a USB_DEVICE_ControlReceive function to the USB_DEVICE_CDC_EVENT_SET_LINE_CODING_EVENT and the data has been received. The application should respond to this event by calling the USB_DEVICE_ControlStatus function with the USB_DEVICE_CONTROL_STATUS_OK flag to acknowledge the received data or the USB_DEVICE_CONTROL_STATUS_ERROR flag to reject it and stall the control transfer.
USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_ABORTED This event occurs when a control transfer that this instance of CDC function driver responded to was aborted by the host. The application can use this event to reset its CDC function driver related control transfer state machine.

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.