| Overview | ||
|---|---|---|
 | Chapter 119. USB Target CDC ACM Protocol Driver |  |
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_codingcallback. -
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 CODINGcommand. 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_statecallback. -
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.
| |  | |
| Chapter 119. USB Target CDC ACM Protocol Driver |  | Chapter 120. USB Host CDC ACM Protocol Driver |
| 2024-03-18 | eCosPro Non-Commercial Public License |