Chapter 163. CDC-EEM Target USB driver

163.1. Introduction

eCosPro-CDCEEM is eCosCentric's commercial name for the USB peripheral
device CYGPKG_DEVS_ETH_USB_CDCEEM package. The
package is not included as standard in eCosPro Developer's Kit
releases, but is available as a separate add-on package.

The CYGPKG_DEVS_ETH_USB_CDCEEM package implements a
USB peripheral device CDC-EEM transport driver. The current
implementation makes use of the generic Ethernet driver
package CYGPKG_DEVS_ETH_GENERIC_DIRECT to integrate
with the lwIP TCP/IP stack.

The CDC-EEM peripheral driver is currently limited to use with the lwIP
network stack, and is not available for the BSD network stacks. This
is a limitation of the
parent CYGPKG_DEVS_ETH_GENERIC_DIRECT package, and
not explicitly a limitation of this CDC-EEM peripheral driver.

Normally the eCos lwIP network interface should be configured to use
AutoIP, so that a link-local network address is
assigned. This ensures that when connected to hosts that do not
provide a DHCP daemon, or support for routing to manual or application
set network addresses, an automatic connection is still configured.

163.2. API

There is no “user” API as such, since
the cyg_eth_drv_generic_transport_cdceem structure
is exported via the __ETH_TRANSPORT_TAB__ table
constructed at build-time, and referenced from the generic Ethernet
device driver. The CDC-EEM driver just provides a transport driver for
the generic Ethernet world.

The exported CDC-EEM device features are controlled by the CDL for the
package.

163.3. Configuration

This section shows how to include the CDC-EEM support into an eCos
configuration, and how to configure it once installed.

163.3.1. Configuration Overview

The CDC-EEM driver is contained in a single eCos
package CYGPKG_DEVS_ETH_USB_CDCEEM. However, it
depends on the services of a collection of other packages for complete
functionality. Currently the CDC-EEM implementation is tightly bound
with the generic Ethernet driver
package CYGPKG_DEVS_ETH_GENERIC_DIRECT.

Incorporating the CDC-EEM driver into your application is
straightforward. The essential starting point is to incorporate the
CDC-EEM eCos package (CYGPKG_DEVS_ETH_USB_CDCEEM) into
your configuration.

This may be achieved directly using ecosconfig add on the
command line, or the Build->Packages… menu item
within the eCos Configuration Tool.

163.3.1.1. Configuring the CDC-EEM driver

Once added to the eCos configuration, the CDC-EEM package has a number
of configuration options.

CYGPKG_DEVS_ETH_USB_CDCEEM_VID

The device VendorID. The VendorID number space is managed by the USB
organisation, www.usb.org, and
a unique ID must be formally obtained.

In conjunction with
the CYGPKG_DEVS_ETH_USB_CDCEEM_PID value this is
used to uniquely identify a specific peripheral product to the host
O/S environment.

Note

The VID is normally expressed as a 16-bit hexadecimal number, but the
eCos graphical configurarion tool will normally display the value as a
decimal.

CYGPKG_DEVS_ETH_USB_CDCEEM_PID

The device ProductID. The ProductID number space is managed by the
vendor. This ID is sometimes used to uniquely identify specific
devices as regards the host device driver needed to communicate with
the target device. It is the responsibility of the developer to manage
this internal (company) number space.

Note

The PID is normally expressed as a 16-bit hexadecimal number, but the
eCos graphical configurarion tool will normally display the value as a
decimal.

CYGPKG_DEVS_ETH_USB_CDCEEM_MANUFACTURER

A human-readable device manufacturer identification string, that is
returned as part of the device USB description. The string may be used
by the host O/S in its description of the product presented to
end-users.

CYGPKG_DEVS_ETH_USB_CDCEEM_PRODUCT

A human-readable product identification string, that is returned as
part of the device USB description. Like the manufacturer string this
may be used on the host when presenting a device to the user.

CYGPKG_DEVS_ETH_USB_CDCEEM_SERIAL_FIXED

Depending on the product requirements the serial number returned as
part of the USB descriptor can either be supplied at run-time by the
application HAL or defined by the CDL and fixed for a binary
build.

The former approach relies on the HAL having a method of obtaining a
unique identifier from the hardware from which to construct a unique
serial number string. This is normally the preferred approach to providing
per-device unique identification, and is used when this option is
disabled. When this option
is enabled the build uses the string defined by
this option as the value returned in the device USB description. This
latter approach is less flexible if different physical devices need a
unique ID since the CDL will need to be modified and a unique binary
constructed for each specific device. If the devices do not need to
present a unique identity then the same serial number can be
configured into the binary build with the same value being used
across all target devices.

CYGPKG_DEVS_ETH_USB_CDCEEM_POWERED

This option defines how the device declares its power state to the
host, and should be configured to match the hardware implementation
supporting the CDC-EEM target driver. When configured
as Bus powered then a further configuration option
is made available:

CYGPKG_DEVS_ETH_USB_CDCEEM_MAXPOWER

When bus-powered this option specifies the maximum power consumption
of the device.

CYGIMP_CDCEEM_CRC_RX

When enabled verify EEM packet CRC on reception. If disabled then the
CRC is ignored and all received packets are passed to the parent
Ethernet driver.

CYGIMP_CDCEEM_CRC_TX

If enabled then a CRC is calculated for every EEM packet
transmitted. When disabled the special 0xDEADBEEF CRC sentinel is
used. NOTE: It is recommended to leave this option disabled currently,
since problems have been seen where Linux host drivers will
incorrectly calculate the CRC and drop packets."

CYGDBG_CDCEEM_DIAGNOSTICS

When enabled this option allows diagnostic output to be generated for
different subsystems within the CDC-EEM driver, and a set of further
options are made available for configuration. This information is
primarily for internal driver development, and is not normally needed
when debugging applications using the USB CDC-EEM network driver. The
debug output is sent to the diagnostic console channel as configured
for the application.

163.4. Debug and Test

163.4.1. Debugging

163.4.1.1. Asserts

If the target platform resources allow the first step in debugging
should be to enable ASSERTs. The inclusion of
assert checking will increase the code footprint and lower the
performance, but do allow the code to catch internal errors from
unexpected data values. e.g. when the application/client is not able
to guarantee the validity of data passed into the CDC-EEM layer.

The CDC-EEM transport driver asserts are controlled via the standard eCos
Infrastructure CYGPKG_INFRA
package CYGDBG_USE_ASSERTS option. If enabled then
run-time assertion checks are performed by the CDC-EEM driver.

If assertions are enabled, and a debugger is being used it is normally
worth-while setting a breakpoint on
the cyg_assert_fail symbol so that the debugger
will stop prior to entering the default busy-loop processing.

163.4.1.2. Diagnostic Output

When CYGDBG_CDCEEM_DIAGNOSTICS is enabled a set of
individually selectable sub-systems are available to control the
diagnostic output generated.

However, when developing or debugging the CDC-EEM driver
implementation it may be simpler (with less build side-effects) to
control the debugging output via uncommenting the necessary manifests
at the head of
the src/cdceem.c source file
than re-configuring the complete eCos configuration via the CDL. That
way only the CDC-EEM package will be re-built.

Note

Some diagnostic output if enabled may adversely affect the operation
of the CDC-EEM driver as seen by 3rd-party code. For example,
“slow” serial diagnostic output of the packet parsing and
response generation could mean that a significant amount of time
passes, such that the CDC-EEM driver no longer adheres to the timings
required by the USB host driver.