AN00124: USB CDC Class as Virtual Serial Port£££doc/rst/an00124.html#an00124-usb-cdc-class-as-virtual-serial-port

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$CMakeLists.txt additions for this example£££task-diagram.html#cmakelists-txt-additions-for-this-example

To start using the USB library, you need to add lib_xud to your CMakeList.txt file, for example:

set (APP_DEPENDENT_MODULES "lib_xud")

You can then access the USB functions in your source code via the xud_device.h header file:

#include "xud_device.h"

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Source code files£££task-diagram.html#source-code-files

The example application consists of the following files:

main.xc
xud_cdc.xc
xud_cdc.h

xud_cdc.xc contains the CDC ACM implementation which includes the USB descriptors, endpoints handler functions and the xC interface (APIs) for application programs. The xud_cdc.h header is included in the main.xc to use the APIs exposed by xud_cdc.xc. The main.xc implements the application logic that interacts over the USB CDC link with a host terminal application.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Declaring resource and setting up the USB components£££task-diagram.html#declaring-resource-and-setting-up-the-usb-components

main.xc contains the application implementation for a device based on the USB CDC device class. There are some defines in it that are used to configure the XMOS USB device library. These are displayed below.

/* USB Endpoint Defines */
#define XUD_EP_COUNT_OUT   2    //Includes EP0 (1 OUT EP0 + 1 BULK OUT EP)
#define XUD_EP_COUNT_IN    3    //Includes EP0 (1 IN EP0 + 1 INTERRUPT IN EP + 1 BULK IN EP)

/* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also
 * if the endpoint wishes to be informed of USB bus resets
 */
XUD_EpType epTypeTableOut[XUD_EP_COUNT_OUT] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_BUL};
XUD_EpType epTypeTableIn[XUD_EP_COUNT_IN] =   {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_INT, XUD_EPTYPE_BUL};

These defines describe the endpoints configuration for this device. This example has bi-directional communication with the host machine via the standard endpoint0 and three other endpoints for implementing the part of our CDC class device.

These defines are passed to the setup function for the USB library which is called from main().

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$The application main() function£££task-diagram.html#the-application-main-function

Below is the source code for the main function of this application, which is taken from the source file main.xc

int main()
{
    /* Channels to communicate with USB endpoints */
    chan c_ep_out[XUD_EP_COUNT_OUT], c_ep_in[XUD_EP_COUNT_IN];

    /* Interface to communicate with USB CDC (Virtual Serial) */
    interface usb_cdc_interface cdc_data;

    par
    {
        on USB_TILE: XUD_Main(c_ep_out, XUD_EP_COUNT_OUT, c_ep_in, XUD_EP_COUNT_IN,
                      null, epTypeTableOut, epTypeTableIn,
                      XUD_SPEED_HS, XUD_PWR_BUS);

        on USB_TILE: Endpoint0(c_ep_out[0], c_ep_in[0]);

        on USB_TILE: CdcEndpointsHandler(c_ep_in[1], c_ep_out[1], c_ep_in[2], cdc_data);

        on tile[1]: app_virtual_com(cdc_data);
    }
    return 0;
}

Looking at this in a more detail you can see the following:

• The par statement starts four separate tasks in parallel.

• There is a task to configure and execute the USB library: XUD_Main(). This library call runs in an infinite loop and handles all the underlying USB communications and provides abstraction at the endpoints level.

• There is a task to startup and run the Endpoint0 code: Endpoint0(). It handles the control endpoint zero and must be run in a separate logical core inorder to promptly respond to the control requests from host.

• There is a task to handle all the other three endpoints required for the CDC class: CdcEnpointsHandler(). This function handles one bulk OUT and one bulk IN endpoints for data transmissions and one interrupt IN endpoint for sending notifications to host.

• There is a task to run the application logic that interacts with user over the virtual serial port: app_virtual_com().

• The define USB_TILE describes the tile on which the individual tasks will run.

• The xCONNECT communication channels and the xC interface cdc_data used for inter task communication are setup at the beginning of main() and passed on to respective tasks.

• The USB defines discussed earlier are passed into the function XUD_Main().

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Configuring the USB Device ID£££task-diagram.html#configuring-the-usb-device-id

The USB ID values used for vendor ID, product ID and device version number are defined in the file xud_cdc.xc. These are used by the host machine to determine the vendor of the device (in this case XMOS) and the product plus the firmware version.

/* USB CDC device product defines */
#define BCD_DEVICE  0x0100
#define VENDOR_ID   0x20B1
#define PRODUCT_ID  0x0401

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$USB Descriptors£££task-diagram.html#usb-descriptors

USB CDC class device has to support class-specific descriptors apart from the standard descriptors defined in the USB specifications. These class specific descriptors are customized according to the need of the USB CDC device. In the example application code, the descriptors implement the ACM model of the CDC class and are customized to suit a virtual serial port.

Fig. 3 shows the descriptors used in the example code.

/* USB Device Descriptor */
static unsigned char devDesc[] =
{
    0x12,                  /* 0  bLength */
    USB_DESCTYPE_DEVICE,   /* 1  bdescriptorType - Device*/
    0x00,                  /* 2  bcdUSB version */
    0x02,                  /* 3  bcdUSB version */
    USB_CLASS_COMMUNICATIONS,/* 4  bDeviceClass - USB CDC Class */
    0x00,                  /* 5  bDeviceSubClass  - Specified by interface */
    0x00,                  /* 6  bDeviceProtocol  - Specified by interface */
    0x40,                  /* 7  bMaxPacketSize for EP0 - max = 64*/
    (VENDOR_ID & 0xFF),    /* 8  idVendor */
    (VENDOR_ID >> 8),      /* 9  idVendor */
    (PRODUCT_ID & 0xFF),   /* 10 idProduct */
    (PRODUCT_ID >> 8),     /* 11 idProduct */
    (BCD_DEVICE & 0xFF),   /* 12 bcdDevice */
    (BCD_DEVICE >> 8),     /* 13 bcdDevice */
    0x01,                  /* 14 iManufacturer - index of string*/
    0x02,                  /* 15 iProduct  - index of string*/
    0x03,                  /* 16 iSerialNumber  - index of string*/
    0x01                   /* 17 bNumConfigurations */
};

/* USB Configuration Descriptor */
static unsigned char cfgDesc[] = {

  0x09,                       /* 0  bLength */
  USB_DESCTYPE_CONFIGURATION, /* 1  bDescriptortype - Configuration*/
  0x43, 0x00,                 /* 2  wTotalLength */
  0x02,                       /* 4  bNumInterfaces */
  0x01,                       /* 5  bConfigurationValue */
  0x04,                       /* 6  iConfiguration - index of string */
  0x80,                       /* 7  bmAttributes - Bus powered */
  0xC8,                       /* 8  bMaxPower - 400mA */

  /* CDC Communication interface */
  0x09,                       /* 0  bLength */
  USB_DESCTYPE_INTERFACE,     /* 1  bDescriptorType - Interface */
  0x00,                       /* 2  bInterfaceNumber - Interface 0 */
  0x00,                       /* 3  bAlternateSetting */
  0x01,                       /* 4  bNumEndpoints */
  USB_CLASS_COMMUNICATIONS,   /* 5  bInterfaceClass */
  USB_CDC_ACM_SUBCLASS,       /* 6  bInterfaceSubClass - Abstract Control Model */
  USB_CDC_AT_COMMAND_PROTOCOL,/* 7  bInterfaceProtocol - AT Command V.250 protocol */
  0x00,                       /* 8  iInterface - No string descriptor */

  /* Header Functional descriptor */
  0x05,                      /* 0  bLength */
  USB_DESCTYPE_CS_INTERFACE, /* 1  bDescriptortype, CS_INTERFACE */
  0x00,                      /* 2  bDescriptorsubtype, HEADER */
  0x10, 0x01,                /* 3  bcdCDC */

  /* ACM Functional descriptor */
  0x04,                      /* 0  bLength */
  USB_DESCTYPE_CS_INTERFACE, /* 1  bDescriptortype, CS_INTERFACE */
  0x02,                      /* 2  bDescriptorsubtype, ABSTRACT CONTROL MANAGEMENT */
  0x02,                      /* 3  bmCapabilities: Supports subset of ACM commands */

  /* Union Functional descriptor */
  0x05,                     /* 0  bLength */
  USB_DESCTYPE_CS_INTERFACE,/* 1  bDescriptortype, CS_INTERFACE */
  0x06,                     /* 2  bDescriptorsubtype, UNION */
  0x00,                     /* 3  bControlInterface - Interface 0 */
  0x01,                     /* 4  bSubordinateInterface0 - Interface 1 */

  /* Call Management Functional descriptor */
  0x05,                     /* 0  bLength */
  USB_DESCTYPE_CS_INTERFACE,/* 1  bDescriptortype, CS_INTERFACE */
  0x01,                     /* 2  bDescriptorsubtype, CALL MANAGEMENT */
  0x03,                     /* 3  bmCapabilities, DIY */
  0x01,                     /* 4  bDataInterface */

  /* Notification Endpoint descriptor */
  0x07,                         /* 0  bLength */
  USB_DESCTYPE_ENDPOINT,        /* 1  bDescriptorType */
  (CDC_NOTIFICATION_EP_NUM | 0x80),/* 2  bEndpointAddress */
  0x03,                         /* 3  bmAttributes */
  0x40,                         /* 4  wMaxPacketSize - Low */
  0x00,                         /* 5  wMaxPacketSize - High */
  0xFF,                         /* 6  bInterval */

  /* CDC Data interface */
  0x09,                     /* 0  bLength */
  USB_DESCTYPE_INTERFACE,   /* 1  bDescriptorType */
  0x01,                     /* 2  bInterfacecNumber */
  0x00,                     /* 3  bAlternateSetting */
  0x02,                     /* 4  bNumEndpoints */
  USB_CLASS_CDC_DATA,       /* 5  bInterfaceClass */
  0x00,                     /* 6  bInterfaceSubClass */
  0x00,                     /* 7  bInterfaceProtocol*/
  0x00,                     /* 8  iInterface - No string descriptor*/

  /* Data OUT Endpoint descriptor */
  0x07,                     /* 0  bLength */
  USB_DESCTYPE_ENDPOINT,    /* 1  bDescriptorType */
  CDC_DATA_RX_EP_NUM,       /* 2  bEndpointAddress */
  0x02,                     /* 3  bmAttributes */
  0x00,                     /* 4  wMaxPacketSize - Low */
  0x02,                     /* 5  wMaxPacketSize - High */
  0x00,                     /* 6  bInterval */

  /* Data IN Endpoint descriptor */
  0x07,                     /* 0  bLength */
  USB_DESCTYPE_ENDPOINT,    /* 1  bDescriptorType */
  (CDC_DATA_TX_EP_NUM | 0x80),/* 2  bEndpointAddress */
  0x02,                     /* 3  bmAttributes */
  0x00,                     /* 4  wMaxPacketSize - Low byte */
  0x02,                     /* 5  wMaxPacketSize - High byte */
  0x01                      /* 6  bInterval */
};

  0x00,                     /* 4  wMaxPacketSize - Low byte */
  0x02,                     /* 5  wMaxPacketSize - High byte */

  0x10, 0x01,                /* 3  bcdCDC */

  0x02,                      /* 3  bmCapabilities: Supports subset of ACM commands */

  0x03,                     /* 3  bmCapabilities, DIY */

  /* String table - unsafe as accessed via shared memory */
  static char * unsafe stringDescriptors[]=
  {
    "\x09\x04",             /* Language ID string (US English) */
    "XMOS",                 /* iManufacturer */
    "CDC Virtual COM Port", /* iProduct */
    "0123456789"            /* iSerialNumber */
    "Config",               /* iConfiguration string */
  };

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$USB Standard and Class-Specific requests£££id3.html#usb-standard-and-class-specific-requests

In xud_cdc.xc there is a function Endpoint0() which handles all the USB control requests sent by host to control endpoint 0. USB control requests includes both standard USB requests and the CDC class-specific requests.

In Endpoint0() function, a USB request is received as a setup packet by calling USB_GetSetupPacket() library function. The setup packet structure is then examined to distinguish between standard and class-specific requests.

The XMOS USB library provides a function USB_StandardRequests() to handle the standard USB requests. This function is called with setup packet and descriptors structures as shown below

            /* Returns  XUD_RES_OKAY if handled okay,
             *          XUD_RES_ERR if request was not handled (STALLed),
             *          XUD_RES_RST for USB Reset */
            unsafe{
            result = USB_StandardRequests(ep0_out, ep0_in, devDesc,
                        sizeof(devDesc), cfgDesc, sizeof(cfgDesc),
                        null, 0, null, 0, stringDescriptors, sizeof(stringDescriptors)/sizeof(stringDescriptors[0]),
                        sp, usbBusSpeed);
             }

The CDC Communication interface uses endpoint 0 as management element and receives class-specific control requests on it. The following code shows how the class-specific requests are filtered and passed to a function ControlInterfaceClassRequests() for further handling.

            switch(bmRequestType)
            {
                /* Direction: Device-to-host and Host-to-device
                 * Type: Class
                 * Recipient: Interface
                 */
                case USB_BMREQ_H2D_CLASS_INT:
                case USB_BMREQ_D2H_CLASS_INT:

                    /* Inspect for CDC Communications Class interface num */
                    if(sp.wIndex == 0)
                    {
                        /* Returns  XUD_RES_OKAY if handled,
                         *          XUD_RES_ERR if not handled,
                         *          XUD_RES_RST for bus reset */
                        result = ControlInterfaceClassRequests(ep0_out, ep0_in, sp);
                    }
                    break;
            }

The ControlInterfaceClassRequests() function handles a subset of CDC ACM requests which are defined in the xud_cdc.xc as follows:

/* CDC Communications Class requests */
#define CDC_SET_LINE_CODING         0x20
#define CDC_GET_LINE_CODING         0x21
#define CDC_SET_CONTROL_LINE_STATE  0x22
#define CDC_SEND_BREAK              0x23

In virtual serial port, the above commands are used to set and get serial port parameters like baud rate, parity, stop bits etc and also to emulate hardware flow control using DTR (Data Terminal Ready) and RTS (Request To Send) signals.

You can use the functions ControlInterfaceClassRequests() and the Endpoint0() as reference to handle more commands of the subclass or you can even implement a different model/subclass for your USB CDC device.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Data handling£££id3.html#data-handling

The two bulk data endpoints of the CDC Data interface are handled by the task CdcEndpointsHandler() present in xud_cdc.xc. As there is no subprotocol used, the bytes received through these endpoints represent the raw data sent from a host terminal software. This data is handled using a double buffer mechanism and hence increases the performance of the device.

To handle asynchronous communication over two endpoints, events are used by means of select statements as shown in the following piece of code from CdcEndpointsHandler() task.

      select
      {
        case XUD_GetData_Select(c_epbulk_out, epbulk_out, length, result):

           if(result == XUD_RES_OKAY)
           {
               /* Received some data */
               rxLen[!readBufId] = length;

               /* Check if application has completed reading the read buffer */
               if(rxLen[readBufId] == 0) {
                   /* Switch buffers */
                   readBufId = !readBufId;
                   readIndex = 0;
                   /* Make the OUT endpoint ready to receive data */
                   XUD_SetReady_Out(epbulk_out, rxBuf[!readBufId]);
               } else {
                   /* Application is still reading the read buffer
                    * Say that another buffer is also waiting to be read */
                   readWaiting = 1;
               }
           } else {
               XUD_SetReady_Out(epbulk_out, rxBuf[!readBufId]);
           }
           break;

        case XUD_SetData_Select(c_epbulk_in, epbulk_in, result):

            /* Packet sent successfully when result in XUD_RES_OKAY */
            if (0 != txLen) {
                /* Data available to send to Host */
                XUD_SetReady_In(epbulk_in, txBuf[writeBufId], txLen);
                /* Switch write buffers */
                writeBufId = !writeBufId;
                txLen = 0;
            } else {
                writeWaiting = 1;
            }

            break;

When OUT endpoint receives data, an event is triggered and the XUD_GetData_Select() case is executed. Similary, when IN endpoint completes sending data to host the XUD_SetData_Select() case is executed. This event driven approach not only handles multiple endpoints but also provides way to include other events and build more logic into the task.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Application interface£££id3.html#application-interface

The application interface is the set of functions defined as xC interface that enables application tasks to send/receive data over the USB CDC endpoints. This API funtions abstract out all the buffering implementation details done at the endpoint level for data communications. This xC interface is declared in xud_cdc.h file and it is shown below.

interface usb_cdc_interface {

    [[guarded]] void put_char(char byte);

    [[guarded]] char get_char(void);

    [[guarded]] int write(unsigned char data[], REFERENCE_PARAM(unsigned, length));

    [[guarded]] int read(unsigned char data[], REFERENCE_PARAM(unsigned, count));

    int available_bytes(void);

    void flush_buffer(void);
};

These interface functions pass arguments and return values over xCONNECT channels and provides well defined inter-task communication. The server side of these functions are defined under select case statements in the CdcEndpointsHandler() task.

In the example code, main.xc has the app_virtual_com() function which uses this interface to implement a simple loopback to interact with user. The following code is taken from app_virtual_com() function

void app_virtual_com(client interface usb_cdc_interface cdc)
{
    while (1)
    {
        char cdc_char = cdc.get_char();
        cdc.put_char(cdc_char);
        if (cdc_char == '\r')
            cdc.put_char('\n');
    }
}

In the above code you can observe that the interface’s functions are accessed via a variable ‘cdc’. This variable is the client side of the usb_cdc_interface.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Demo Hardware Setup£££id3.html#demo-hardware-setup

To setup the demo hardware the following boards are required.

• XK-EVK-XU316 board (Fig. 4) - 2 x USB cables (A to micro-b)

The hardware should be configured as follows:

• Connect the USB receptacle of the XK-EVK-XU316 to the host machine using a USB cable

• Connect the DEBUG receptacle XK-EVK-XU316 to the host machine using a USB cable

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Building the application£££hw-board.html#building-the-application

The application uses the xcommon-cmake build system as bundled with the XTC tools.

To configure the build run the following from an XTC command prompt:

cd app_an00124
cmake -G "Unix Makefiles" -B build

If any dependencies are missing it is at this configure step that they will be downloaded by the build system.

Finally, the application binary can be built using xmake:

xmake -C build

This command will cause a binary app_an00124.xe file to be generated in the app_an00124/bin directory,

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Launching the demo application£££hw-board.html#launching-the-demo-application

Once the demo example has been built we can execute the application on the xcore.ai device.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Launching from the command line£££hw-board.html#launching-from-the-command-line

From the command line we use the xrun tool to download code to the xcore device. From an XTC command prompt, from the app_an00124/bin directory, run:

xrun --xscope app_an00124.xe

Once this command has executed the application will be running on the xcore device. The CDC device will have enumerated as virtual serial port on the host machine.

AN00124: USB CDC Class as Virtual Serial Port$$$USB CDC Class application note$$$Running the Virtual COM demo£££hw-board.html#running-the-virtual-com-demo

To run the demo, the host needs to have a serial terminal software installed on it.

Following sections describe in detail on how to run the demo on different OS platforms.