Chapter 167. RNDIS Target USB driver
Table of Contents
eCosPro-RNDIS is eCosCentric's commercial name for the USB peripheral
CYGPKG_DEVS_ETH_USB_RNDIS package. The
package is not included as standard in eCosPro Developer's Kit
releases, but is available as a separate add-on package.
CYGPKG_DEVS_ETH_USB_RNDIS package implements a
USB peripheral device Remote NDIS transport driver. The current
implementation makes use of the generic Ethernet driver
CYGPKG_DEVS_ETH_GENERIC_DIRECT to integrate
with the lwIP TCP/IP stack.
This driver has been tested against a range of host operating systems, including:
Most modern Linux distributions will, by default, have support for RNDIS USB devices. For example, Ubuntu 12, CentOS 6, etc. The target driver has been explicitly tested against
3.8kernel based hosts.
Mac OS X
The 3rd-party, open-source, HoRNDIS driver needs to be installed on the host. The eCos RNDIS driver has been explicitly tested against Mac OS X versions
10.9, though earlier versions of Mac OS X should present no problems assuming available HoRNDIS support.
Windows XP (SP2), 7 (SP1), 8 and 8.1 have been testing using the standard Windows RNDIS host driver support.
The RNDIS 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
CYGPKG_DEVS_ETH_GENERIC_DIRECT package, and
not explicitly a limitation of this RNDIS 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.
One side-effect of the RNDIS networking model (as opposed to CDC-EEM for example) is that two network interfaces exist; the host-end network interface created by the host O/S, and the peripheral lwIP interface providing the target application networking. This means that each device configured to use the RNDIS USB target driver needs to provide two IEEE MAC addresses. The platform HAL support supplying the MAC address to this driver, in conjunction with the developer/manufacturer build world, must be aware of the requirements for managing the “unique identity” 24-bit MAC space in conjunction with the 24-bit IEEE OUI space specific to the device manufacturer.
There is no “user” API as such, since
is exported via the
constructed at build-time, and referenced from the generic Ethernet
device driver. The RNDIS driver just provides a transport driver for
the generic Ethernet world.
The exported RNDIS device features are controlled by the CDL for the package.
This section shows how to include the RNDIS support into an eCos configuration, and how to configure it once installed.
167.3.1. Configuration Overview
The RNDIS driver is contained in a single eCos
CYGPKG_DEVS_ETH_USB_RNDIS. However, it
depends on the services of a collection of other packages for complete
functionality. Currently the RNDIS implementation is tightly bound
with the generic Ethernet driver
Incorporating the RNDIS driver into your application is
straightforward. The essential starting point is to incorporate the
RNDIS eCos package (
This may be achieved directly using ecosconfig add on the command line, or the Build->Packages… menu item within the eCos Configuration Tool.
220.127.116.11. Configuring the RNDIS driver
Once added to the eCos configuration, the RNDIS package has a number of configuration options.
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_RNDIS_PIDvalue this is used to uniquely identify a specific peripheral product to the host O/S environment.
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.
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.
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.
- 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.
- 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.
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.
This option defines how the device declares its power state to the host, and should be configured to match the hardware implementation supporting the RNDIS target driver. When configured as
Buspowered then a further configuration option is made available:
- When bus-powered this option specifies the maximum power consumption of the device.
- When enabled this option allows diagnostic output to be generated for different subsystems within the RNDIS 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 RNDIS network driver. The debug output is sent to the diagnostic console channel as configured for the application.
167.4. Debug and Test
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 RNDIS layer.
The RNDIS transport driver asserts are controlled via the standard eCos
CYGDBG_USE_ASSERTS option. If enabled then
run-time assertion checks are performed by the RNDIS driver.
If assertions are enabled, and a debugger is being used it is normally
worth-while setting a breakpoint on
cyg_assert_fail symbol so that the debugger
will stop prior to entering the default busy-loop processing.
18.104.22.168. Diagnostic Output
In conjuction with the
configuration setting, the
src/rndis.c implements the RNDIS
specific diagnostics control.
CYGDBG_RNDIS_DIAGNOSTICS is enabled a set of
individually selectable sub-systems are available to control the
diagnostic output generated.
However, when developing or debugging the RNDIS 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
src/rndis.c source file
than re-configuring the complete eCos configuration via the CDL. That
way only the RNDIS package will be re-built.
Some diagnostic output if enabled may adversely affect the operation of the RNDIS 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 RNDIS driver no longer adheres to the timings required by the USB host driver.
|2022-01-07||eCosPro Non-Commercial Public License|