Name

Overview — eCosPro Support for FTDI Protocol in Host Mode

Description

This package provides protocol support for a host mode connection to FTDI USB to serial adaptors. 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 FTDI 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, flow control) 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 ftdi protocol driver (CYGPKG_IO_USB_FTDI). 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 FTDI channel needs to be configured using the options below.

The configuration option CYGNUM_IO_USB_FTDI_MAXPKT defines the maximum packet size used for USB transfers. It is used to 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 FTDI 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.

The option CYGPKG_IO_USB_FTDI_SUPPORTED_EXTRA defines an additional set of VID/PID pairs that the driver can support. A user or HAL package can define this to add entries to the table of VID/PID pairs that the driver recognizes as valid devices. This option consists of a comma separated list of initializers for for a VID/PID structure. For example "{ 0x0403, 0x6001 }, …".

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_FTDI_SERIAL0
This interface may be implemented by the platform HAL to instantiate this serial channel.
CYGPKG_IO_USB_FTDI_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_FTDI_SERIAL0, but it may also be enabled with a requires statement or from the configtool.
CYGNUM_IO_USB_FTDI_SERIAL0_NAME
This option defines the name of this channel, which eCos applications should use to access the device via cyg_io_lookup(), open() or similar calls. The default is to set it to "/dev/ftdi0" and so on.
CYGNUM_IO_USB_FTDI_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_FTDI_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_FTDI_MAXPKT and preferably somewhat larger. The default value makes it twice the maximum packet size.
CYGNUM_IO_USB_FTDI_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_FTDI_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.

CYGNUM_IO_USB_FTDI_SERIAL0_LATENCY
This option defines the latency in milliseconds between packets containing data from the FTDI device. If the device has 62 or more bytes available, it will send a packet immediately. Otherwise it will wait this number of milliseconds after the last packet before sending what it has. Decreasing this value will improve responsiveness for low data rate applications at the cost of more activity from the host driver as it processes more packets.

Supported Devices

There is a large family of FTDI devices, some of which support slightly different variants of the communication protocol. It is therefore important to detect what kind of device has been attached. FTDI devices do not have standard class. subclass or protocol codes defined by the USB-IF. Device descriptors have these fields set to zero, to redirect them to the interfaces. The interface fields are set to 0xFF, which is a reserved vendor specific code. Additionally, FTDI devices can have internal or external PROMs from which idVendor, idProduct and string descriptors may be fetched. The result of all this is that the exact identity of an FTDI device can be difficult to determine.

The eCosPro FTDI driver employs a number of strategies to determine whether a device is one that can be supported. The first part of this is a table of VID/PID pairs. Only if a device can be found in this table will it be accepted. By default the table contains the standard FTDI VID/PID values and will be extended to contain the values for any other devices that have been tested. There is also a mechanism that allows users or other packages to add entries to this table using the CYGPKG_IO_USB_FTDI_SUPPORTED_EXTRA option.

If a device passes the VID/PID test, then other descriptor values such as bcdDevice bNumInterface are used to determine which FTDI device model this is likely to be and adjust the protocol used to talk to it accordingly.

The eCos FTDI driver has been successfully tested against the following standard FTDI USB serial adapters:

  • FTDI CHIPI-X10 (FT231X based)
  • FTDI US232R (FT232RL based)
  • FTDI US232B (FT232BM based)

In addition an older FT232R and a FT2232C dual channel based devices from manufacturers other than FTDI have also been tested.