Device driver mode bits and other skulduggery.

[Eric S. Raymond]

Hal Murray <hmurray at megapathdsl.net>:
> bps may not be enough.  There is also the parity and stop bits, but I don't 
> think they are fiddled much.
> 
> The HP driver uses one mode bit to switch from whatever the default is to a 
> different baud rate and parity.  It may be simpler to use a device-type 
> keyword rather than require the user to know about bps and such.
> 
> The NMEA driver uses a chunk of the mode field to select the type of sentence 
> to use.  Something symbolic would be nicer.
> 
> The palisade driver has an option that selects from several modes.
> 
> There are probably others.
> 
> It's probably worth a pass through the code and/or documentation before you 
> do anything.

I've just done that pass.  It turns out setting variable baud rate is
a pretty unusual thing.  The *only* drivers that do it are hpgps, jjy,
nmea and generic; all others are fixed speed. (There might have been
more with variable baud once upon a time, but I've removed for cause
18 of the 42 drivers that existed at the time of the fork.)  And it
looks like only hgpgs messes with parity and stop bits.

Still, I'm a little tempted to implement a speed option just because the NMEA
driver is an important case and the way it uses the mode field is so ugly.
I've figured out exactly how to create a data path from the parser to the
initialization routine by looking at how the ttl/mode option is passed now.

There's not that much else weird stuff going on.  Three drivers, hgpgs and
generic and jjy, use the mode field for device-type selection; I might just
declare 'subtype' as a token alias to make that less cryptic in the new
syntax.

One thing that jumps out at me is that several drivers have a clockstats
verbosity option, always flag4 (which, alas, is used for other things too).

Here's a complete list of interpreted fudges, mode fields, and other
skulduggery. The stratum and refid options are excluded:

acts:
    time1: time offset
    flag1: initiate call
    flag2: enable port locking

arbiter:
    time1: time offset
    flag4: clockstats verbosity flag   

austron:
    time1: time offset
    flag2: listen-only flag (needs investigation - doc looks wrong)
    flag4: clockstats verbosity flag   

chu:
    time1: time offset
    flag2: select audio input port
    flag3: enable audio monitoring

generic:
    Uses PPS
    time1: time offset
    time2: PPS offset or trustability interval, depending on flag1
    flag1: select meaning of time2
    flag2: sample pps on clear not assert
    flag3: link kernel PPS tracking to this refclock instance.
    flag4: delete next leapsecond
    mode: used to select the device type and serial parameters

gpsd:
    time1: PPS time offset
    time2: STI time offset
    flag1: enable secondary as PPS peer
    flag2: disable PPS processing on secondary
    flag3: disable log throttle
    flag4: clockstats verbosity flag
    mode: control STI and strict operating modes
    In addition, the high bit of the unit number is interpreted

hpgps:
    time1: PPS time offset
    mode: select device type


chu:
    time1: time offset
    flag2: select audio input port
    flag3: enable audio monitoring

irig:
    time1: time offset
    flag2: select audio input port
    flag3: enable audio monitoring

jjy:
    time1: time offset
    mode: select device subtype (implies serial-parameter settings)

jupiter:
    Uses PPS
    time1: time offset
    flag1: device mobility flag
    flag2: select PPS edge

local:
    time1: time offset

mx4200:
    Uses PPS
    time1: time offset
    flag2: device mobility flag

neoclock:
    time1: time offset
    flag1: ship timestamps during holdover
    flag2: ship timestamps even if never synced
    flag4: clockstats verbosity flag

nmea:
    Uses PPS
    time1: time offset
    time2: serial eol time offset
    flag1: enable PPS processing
    flag2: pps edge selection
    flag3: clock discipline selection
    flag4: obscure location in timecode
    mode: select speed, sentence mix, and logging.

oncore:
    Uses PPS
    time1: time offset

palisade:
    time1: time offset
    flag2: disable hardware event capture
    mode: select device subtype.

pps:
    time1: time offset
    flag2: PPS edge select
    flag3: PPS discipline select
    flag4: clockstats verbosity flag

shm:
    time1: time offset
    time2: maximum delta allowed
    flag1: skip delta check
    mode: Can be used to set private-mode segments

spectracom:
    Uses PPS
    time1: PPS time offset
    time2: Serial time offset
    flag1: enable PPS
    flag2: PPS edge select
    flag3: clock discipline select
    flag4: clockstats verbosity flag

truetime:
    time1: time offset
    flag1: silent clock (needs better documentation)
    flag2: generate debug file
    flag4: clockstats verbosity flag

Now that I've been through this, it looks like time1 is always a fudge for
most accurate reported time - sometimes PPS time, sometimes in-band.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>