psarc/2009/197 - UFTDI - fast-track

[Tim Marsland]

[Resubmitting with correct 'To:' line and new timeout date
- apologies for duplication.  The case already has a '+1'
from Garrett and Artem - they don't need to resend it!]

I'm sponsoring this fast-track for me.
If approved, the case would time out April 8th 2009.
The release binding sought for these changes is "Patch".
The materials directory contains the manpage for the device.

This project is essentially about adding yet another USB serial
port driver.  In that sense it is uninteresting to the ARC,
because we have already established the architecture for USB
serial port devices in the numerous USB cases that have come
before the ARC over the past eight years.

However, there are two additional issues that this device
driver raises - hence this case.

#1	Support for 921600 baud

There are a number of peripheral devices that choose to use USB
serial port devices internally for the sake of providing a simple
programming model to their users.  These peripherals may only use
a few millimeters of actual RS232 electrical signals, and thus
some surprisingly high baud rates can be supported.

The desire to support 921600 baud comes from a customer
application with a random number generator device that plugs into a
USB port, though it presents a serial port interface using this driver
to extract the random numbers.

The highest baud rate currently supported by Solaris is 460800 baud;
this case proposes to double that to the new maximum of 921600.  Note
that this is really a matter of adding a #define for B921600 to
<sys/termios.h> then also adding support to all the pieces of the
system that "know" about the translation from the baud rate
number to the encoded baud rate passed into the termios structure.

Since this is also a baud rate supported by other open source OSes,
and most applications that support higher baud rates
conditionalize support for this baud rate under
'#ifdef B921600'; recompilation against the updated termios.h
header makes all the open source software i've looked at
"just work" with this new (for solaris) baud rate.

#2	Soft carrier properties (ignore-cd)

The current default for "off-board" serial ports is to carefully
honor the carrier detect line i.e. before /dev/term/N can be opened,
the device must assert DCD.  A complex interaction between /dev/term/N
(a dial-in connection, e.g. enabled for login) and /dev/cua/N (a
dial-out connection, for use with tip etc.) is supported in all
Solaris serial devices which uses the DCD behaviour to implement
this "shared" access method.

However, for as long as I can recall, SPARC firmware and the
simulation of it on x64 systems sets up *onboard* serial
ports to ignore the carrier detect line, enabling "3-wire"
connections - just gnd/rx/tx for a serial port.  This is normally
controlled by the 'ignore-cd?' property in SPARC firmware,
or 'tty*-ignore-cd' in bootenv.rc on x86 -- both these properties
are set to 'true', causing cause the state of the DCD line
to be ignored by SW.

This case asserts that, moving forward, the default behaviour
for "off-board" serial ports should be the same as "on-board"
serial ports -- the distinction being particularly ambiguous
in the case of USB simulations of RS232 devices.

To implement this for the UFTDI driver (usbftdi), the driver
ships with a usbftdi.conf file that simply contains the
property

	ignore-cd = 1;

with an additional note that explains that finer-grain
control for this behaviour (on a device instance basis)
can be achieved using

	port-N-ignore-cd = 1;

(e.g. port-4-ignore-cd for serial port 4)

These properties are decoded by the non-device specific
part of the USB serial port infrastructure and have been
present continuously, but have not been documented/exposed
- this case would assign these properties an interface
committment level of 'Stable'.

This case proposes to make the same behaviour true for this
new USB device, and to document the means of enabling this
default for other USB serial devices too.