Overview

Name

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

Description

This package provides protocol driver support for host mode serial adapter connections that use 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.

Usage Model

The eCos serial driver subsystem does not support the dynamic creation and deletion of serial devices. Instead the CDC/ACM driver allocates a number of permanently available serial channels which are allocated to USB devices as they are attached. In order to retain some continuity, it is possible to assign specific Vendor and Product ID values to individual channels so that the USB device will be allocated the same channel each time it is attached.

Writing data to a detached channel will result in that data being lost, just as if it were being written to a disconnected serial line. A detached channel will not produce any data. Changes to the line configuration (baud rate, parity, stop bits, data size) will be stored and applied to the device once it is attached.

Applications may install a serial line callback function which will be called with the which field set to CYGNUM_SERIAL_STATUS_ATTACH and the value field set to zero for a detach and one for an attach.

Configuration

To use this package, various other packages need to be included and configuration options need to be set. The packages that need to be included are: USB Support (CYGPKG_IO_USB), USB serial driver (CYGPKG_IO_SERIAL_USB), Serial device drivers (CYGPKG_IO_SERIAL) and this package USB host cdc acm protocol driver (CYGPKG_IO_USB_CDC_ACM_HOST). Packages can be added directly using ecosconfig add on the command line, or the Build->Packages... menu item within the eCos Configuration Tool. Depending on your platform some of these may already be present in the default eCos configuration. To activate the requisite USB host and serial support, the options CYGPKG_IO_USB_HOST and CYGPKG_IO_SERIAL_DEVICES need to be enabled. Following this at least one CDC/ACM channel needs to be configured using the options below.

The configuration option CYGNUM_IO_USB_CDC_ACM_MAXPKT defines the maximum packet size used for USB transfers. It is used define the size of the the rx_buf in the usb_serial_if structure. The actual packet size used by any device is specified in its descriptors. Most CDC/ACM devices will use a maximum packet size of 64 bytes, and many will be smaller. So this value should not be reduced unless it is known that only devices with smaller packet sizes will be used.

Each serial channel has a number of configuration options associated with it. The following descriptions show the options for serial channel 0, for other channels the zero should be replaced with the number of the channel, currently up to 4.

CYGINT_IO_USB_CDC_ACM_HOST_SERIAL0

This interface may be implemented by the platform HAL to instantiate this serial channel.

CYGPKG_IO_USB_CDC_ACM_HOST_SERIAL0

This is the main component that defines this serial channel, unless this component is enabled, the remaining options will remain undefined. Its default value is derived from CYGINT_IO_USB_CDC_ACM_HOST_SERIAL0, but it may also be enabled with a requires statement or from the configtool.

CYGNUM_IO_USB_CDC_ACM_HOST_SERIAL0_NAME

This option controls the name that an eCos application should use to access this device via cyg_io_lookup(), open(), or similar calls. The default is "/dev/acm0" and so on.

CYGNUM_IO_USB_CDC_ACM_HOST_SERIAL0_BAUD

This option specifies the default baud rate for this channel. Its default value is set to CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL_BAUD.

CYGNUM_IO_USB_CDC_ACM_HOST_SERIAL0_BUFSIZE

This option specifies the size of both the input and output buffer for the common serial I/O driver layer. This should be at least equal to CYGNUM_IO_USB_CDC_ACM_HOST_MAXPKT and preferably somewhat larger. The default value makes it twice the maximum packet size.

CYGNUM_IO_USB_CDC_ACM_HOST_SERIAL0_VID

This option controls whether this serial channel matches a particular USB Vendor ID. If zero it will match any ID, otherwise this channel will only match a device with the given vendor ID.

CYGNUM_IO_USB_CDC_ACM_HOST_SERIAL0_PID

This option controls whether this serial channel matches a particular USB Product ID. If zero it will match any ID, otherwise this channel will only match a device with the given product ID.

Channels are searched for a VID and PID match in numerical order, skipping any that are already in use. Therefore lower numbered channels should have more specific VID and PID values and generic channels should be at the end of the list.

Protocol Support

This driver only supports a subset of the CDC ACM protocol, sufficient to provide a serial-like interface between the host and the device.

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. Only the following commands are currently sent:

SET LINE CODING

This sets the baud rate, stop bits, parity and character size for the channel. This is generated in response to a CYG_IO_SET_CONFIG_SERIAL_INFO set_config key from the application.

Supported Devices

Any USB serial adapter that implements the standard USB-IF defined CDC ACM protocol should be compatible with the eCosPro host CDC ACM protocol driver. The driver has been tested successfully with the Microchip MCP2200 chip based Microchip MCP2200EV-VCP evaluation board.

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