Overview

Name

Overview -- eCosPro Support for CDC ACM Protocol in Peripheral Mode

Description

This package provides support for a peripheral mode serial connection using the CDC ACM protocol. It needs to be used in conjunction with the USB serial driver package and the reader is referred to that document for additional details.

Configuration

To use this package, various other packages need to be included and configuration options need to be set. The packages that need including are CYGPKG_IO_USB, CYGPKG_IO_SERIAL_USB, CYGPKG_IO_SERIAL and this package CYGPKG_IO_USB_CDC_ACM. To get USB target and serial support running, the options CYGPKG_IO_USB_TARGET and CYGPKG_IO_SERIAL_DEVICES need to be enabled. So long as the hardware USB configuration package defines the target data structures described in the USB serial driver package, a CDC/ACM peripheral will be presented on the selected device port.

The configuration options CYGNUM_IO_USB_CDC_ACM_VID and CYGNUM_IO_USB_CDC_ACM_PID must be configured, respectively, with suitable VendorID and ProductID values. These values are used by hosts to identify a specific USB device. The www.usb.org site provides more information, specifically the Getting a Vendor ID page.

The configuration options CYGPKG_IO_USB_CDC_ACM_MANUFACTURER and CYGPKG_IO_USB_CDC_ACM_PRODUCT allow for human-readable identification strings to be supplied by the device. These strings are returned as part of the device USB description, and may be used by the host O/S in its description of the product as presented to end-users.

The configuration option CYGNUM_IO_USB_CDC_ACM_MAXPKT defines the maximum packet size used for USB transfers. It is used to define fields in the CDC ACM descriptors and must be used to define the size of the the rx_buf in the usb_serial_if structure.

Configuration Packages

The USB driver configuration packages for some target families (e.g. AT91 and STM32) contain configuration for a CDC ACM device instance. These have some common configuration options. In the following descriptions, XXXX should be replaced by the target family name.

The option CYGNUM_DEVS_USB_XXXX_ACM0_BUFSIZE defines the size of the circular buffer for ACM0. This must be sized such that there is always enough space in the buffer for a maximum sized USB packet after the high water mark is reached.

The option CYGPKG_DEVS_USB_XXXX_ACM0_SERIALNO defines the source of the serial number reported in USB string descriptor 3. The CSUM option generates an executable-unique checksum, which is necessary for the eCosCentric test system. The HAL option calls a function supplied by the platform HAL to supply the serial number. The CONST option uses the value of CYGINT_DEVS_USB_XXXX_ACM0_SERIALNO, which is useful for testing. In all cases the serial number is a 32 bit unsigned value which is encoded into the string descriptor in hexadecimal combined with the test crash ID.

The option CYGINT_DEVS_USB_XXXX_ACM0_SERIALNO supplies the constant value for the serial number if the CONST option is selected. This is useful for testing, but is not a viable solution for production devices.

Protocol Support

This driver only supports a minimal subset of the CDC ACM protocol, sufficient to provide a serial-like interface between a host and the target board. Any unrecognized messages will generate an error response; normally a STALL on the control endpoint.

CDC ACM uses two bulk endpoints to transfer raw data bytes between the host and the target board. Additionally, control messages are sent to the control endpoint to adjust the configuration of the channel. The following commands are supported:

SET LINE CODING

This sets the baud rate, stop bits, parity and character size for the channel. These parameters are simply passed on to the USB serial driver by calling the dev_line_coding callback.

GET LINE CODING

This returns the baud rate, stop bits, parity and character size for the channel. Usually this just returns the value set by the last SET LINE CODING command. The data structure is initialized to a default set of values in case it is queried before being set.

SET CONTROL LINE STATE

This sets the state of the RTS and DTR lines. These are passed on to the USB serial driver by calling the dev_control_line_state callback.

SEND BREAK

This sends a BREAK condition on the line. At present this command is accepted and acknowledged but nothing is done to act on it.

Since the protocol driver is not controlling a real UART, these commands have no real effect and are supported mainly to keep host OS drivers happy.

Host Driver Advice

The Linux operating system includes generic support for CDC ACM class devices and automatically supports standards conforming CDC ACM based devices.

Whilst Windows also includes built-in generic CDC ACM support, it has to be enabled with a specially crafted .inf file. You may alternatively elect to use a third party CDC ACM class driver as this can provide better functionality, reliability and install support compared to the Windows built-in driver.

In-depth information concerning Windows USB class support along with the use, configuration and installation of associated .inf files, are beyond the scope of this documentation. The Microsoft Developer Network documentation should be consulted for specific details. Relevant sections include Windows USB support and USB class drivers included in Windows.

As an aid in the use of Windows built-in CDC ACM class support an example .inf file has been provided here: packages/devs/usb/pcd/class/cdc_acm/<version>/host/cdcacm-generic.inf The .inf file will need to be tailored to match your specific manufacturer VID and PID numbers, as well as manufacturer and device description strings. You will need to modify all the VID and PID references in the [DeviceList] sections, as well as the MFGNAME and DESCRIPTION strings at the end of the file. To enable CDC ACM on a specific Windows system the user should right-click on the .inf file and select the "Install" option from the pop-up menu. A Windows driver validation dialog box will appear, from which the "Install this driver software anyway" option should be selected.

Depending on the Windows version you are using, the CDC ACM driver installation may not be automatic on the first connection of your CDC ACM class device. An error may be reported in finding a suitable device driver during device insertion, or the Device Manager may show your device, but with an associated warning triangle. In these cases you will need to manually select the correct class driver. To accomplish this, right-click on the new entry in the "Ports" section of the Device Manager and select "Update Driver Software" from the pop-up menu. In the following dialog select "Browse my computer for driver software". You should then select the "Let me pick from a list of device drivers on my computer" from the available options that are then displayed. At this point you will then be presented with a list of device types - select "Ports (COM & LPT)" and then the "Next" button. You should then be able to find your company name in the Manufacturer list, and the Model associated with your driver entry - select this and hit the "Next" button. A Warning dialog concerning device verification will appear, select "Yes" to continue and install the driver. A confirmation message indicating the driver has installed should then appear.

Each time an eCos CDC ACM device is plugged in an entry should become visible within the "Ports" section of the Device Manager. The entry's device name should include an associated automatically assigned COM port number in brackets. You should be able to connect to this assigned COM port to communicate with your device.

2017-02-09
Documentation license for this page: eCosPro License