
**********************************
*** Custom Serial Applications ***
**********************************

This document describes the programming interface
used by custom serial communications applications.
This interface uses the standard Linux system calls
and tty/termios functions.

Sample applications are included for each serial protocol
and are the best place to start for understanding the interface.

    sample-async         asynchronous application
    sample-bisync	 byte synchronous 16-bit flag application
    sample-external      limited external synchronization application
    sample-monosync	 byte synchronous 8-bit flag application
    sample-sdlc          bit synchronous SDLC application
    sample-sdlc-encoded  bit synchronous SDLC application with DPLL recovery


Applications must include the "seamac.h" header file.

Contents
--------
Overview
Open/Close Device
Configure Device
Receiving Data
Sending Data
Ioctl() codes
DPLL Clock Recovery
Asynchronous Communications
N_TTY line discipline


****************
*** Overview ***
****************

The device interface uses standard Linux system calls and tty/termios functions:

System Calls
------------
open()      open handle to device (required for other calls)
read()      get received data
write()     send data
ioctl()     monitor/control/configure device
close()     release handle to device

tty/termios Functions
---------------------
tcdrain()

For more information about system calls,
refer to the man pages or other documentation.


*************************
*** Open/Close Device ***
*************************

   char devname[] = "/dev/ttySM0"; // device name
   int fd;                         // file descriptor

   fd = open(devname, O_RDWR | O_NONBLOCK, 0);
   ...
   close(fd);

open() returns a file descriptor for use with other functions.
O_RDWR is required to send and receive data.
O_NONBLOCK causes open() to return without waiting for
the serial status signal DCD to be active.

close() releases the file descriptor when done.


************************
*** Configure Device ***
************************

The application must configure the device before use. This is done using
ioctl() calls as described below in the sections for SEAMAC_IOCTL_GPARAMS
(Get Parameters) and SEAMAC_IOCTL_SPARAMS (Set Parameters). The specific 
options are application dependent.


**********************
*** Receiving Data ***
**********************

   int fd;                        // open file descriptor
   int size = 4096;               // size of buffer (max frame size)
   char buf[size];                // buffer for received frame
   int rc;                        // read() return value

   rc = read(fd, buf, size);
   if (rc < 0) {
      // process error
   } else {
      // process rc bytes of data
   }


Monosync mode -- DO NOT use the n_hdlc line discipline in this mode of operation
-------------
read() returns all incoming data once synchronization is achieved.  The device 
will search the incoming data stream for the defined sync flag.  Until the sync 
flag is identified no data will be shifted into the data FIFO.  When a sync 
flag is detected, all following data will enter the FIFO including sync flags.
The user application must determine when the end of message has occurred and
attempt to restore synchronization with the SEAMAC_IOCTL_HUNT ioctl or shutdown
the port.


Bisync mode -- DO NOT use the n_hdlc line discipline in this mode of operation.
-----------
read() returns all incoming data once synchronization is achieved.  The device 
will search the incoming data stream for the defined sync flag.  Until the sync 
flag is identified no data will be shifted into the data FIFO.  When a sync 
flag is detected, all following data will enter the FIFO including sync flags.
The user application must determine when the end of message has occurred and
attempt to restore synchronization with the SEAMAC_IOCTL_HUNT ioctl or shutdown
the port.

Bisync-framed mode -- MUST use n_hdlc line discipline or frames may be broken
------------------
read() returns only data framed by 0x5c5c.  This is a custom mode for the
9198 hardware only.  Standard Bisync HUNT mode is not supported, the hardware
controls receive synchronization completely.


SDLC mode -- MUST use n_hdlc line discipline or frames may be broken apart
---------
read() returns a complete frame of data,
including the address and control fields and the CRC value
but not the leading/closing flags. If a frame is larger
than buf, read() returns -1 and errno is set to EOVERFLOW.

The driver discards valid frames with address fields other than
the broadcast address (0xFF) or the addrfilter field of the
seamac_params structure. If addrfilter is set to 0xFF, all frames
are passed to application without regard for the address field.


Asynchronous mode
-----------------
read() returns one or more data characters.


General
-------
O_NONBLOCK cleared (blocking mode): read() blocks
until data is available.

O_NONBLOCK set (polling mode): read() returns immediately,
either with data (rc > 0) or a return value of -1 and
errno set to EAGAIN.


********************
*** Sending Data ***
********************

   int fd;                        // open file descriptor
   int size = 2;                  // size of data in buffer (minimum sdlc size)
   char buf[size];                // buffer for send frame
   int rc;                        // write() return value

   // initialize buf with send data
   // initialize size with count of send data bytes

   rc = write(fd, buf, size);
   if (rc < 0) {
      // process error
   } else {
      // rc bytes of data successfully sent
   }


SDLC mode  -- MUST use n_hdlc line discipline or frames could be broken apart
---------
write() sends one frame. buf contains the SDLC information
field, including the address and control fields. The hardware
adds the CRC and opening/closing flags.  size must be at least 2 
(smallest valid SDLC frame).


Monosync mode
-------------
write() sends one frame.  The format of the output frame is entirely up to
the user application.  The only forced setting by the device driver is to add
the opening sync flag to the data stream.  The frame must be properly terminated
by the user application.


Bisync mode
-----------
write() sends one frame.  The format of the output frame is entirely up to
the user application.  The only forced setting by the device driver is to add
the opening sync flag to the data stream.  The frame must be properly terminated
by the user application if it must be read back by the device driver.


Bisync-Framed mode
-----------
write() sends one frame.  The format of the output frame is entirely up to
the user application.  No sync flags are added by the hardware.  This mode
is only supported in custom 9198 hardware.


Asynchronous mode
-----------------
write() sends one or more bytes of asynchronous data.


General
-------
O_NONBLOCK clear (blocking mode)
write() blocks until data is accepted and
rc is set to size on return.

O_NONBLOCK set (polling mode)
write() accepts data and rc is set to size,
or rc is set to -1 and errno is set to EAGAIN indicating
the application should try again later. EAGAIN occurs if
all send buffers are full.

write() returns before all data has been sent. The data
is buffered in the driver and hardware. Use the function
tcdrain() or ioctl(TIOCOUTQ) to determine when all data
has been sent.


*********************
*** ioctl() codes ***
*********************

Standard tty ioctl() codes
--------------------------

   TIOCMGET      get modem control and status signal states

   TIOCMBIS      enable specified modem control signals
   TIOCMBIC      disable specified modem control signals
   TIOCMSET      set state of specified modem control signals

   TIOCMIWAIT    wait for serial status signal changes

   TIOCGICOUNT   get count of serial status signal changes

   TIOCOUTQ      get count of pending send data

Seamac Specific ioctl() codes
-----------------------------

   SEAMAC_IOCTL_GPARAMS      get device configuration
   SEAMAC_IOCTL_SPARAMS      set device configuration
   SEAMAC_IOCTL_HUNT         enter synchronization hunt mode (Mono, Bi, Ext)
   SEAMAC_IOCTL_GTXACTIVE    determine if transmitter is active
   SEAMAC_IOCTL_GSECURITY    get the factory programmed port security key
   SEAMAC_IOCTL_GSIGNALS     get a mask of active modem control signals
   SEAMAC_IOCTL_SSIGNALS     sets the state of output modem control signals


TIOCMGET - Get Modem Signals
----------------------------

   int sigs;
   rc = ioctl(fd, TIOCMGET, &sigs);

Return serial control and status signals in sigs argument.
Active signals are indicated with following bit definitions:
For additional signals (LL&RL) see SEAMAC_IOCTL_GSIGNALS

   TIOCM_RTS   Request To Send (output signal)
   TIOCM_DTR   Data Terminal Ready (output signal)
   TIOCM_CAR   Data Carrier Detect (input signal)
   TIOCM_RNG   Ring Indicator (input signal)
   TIOCM_DSR   Data Set Ready (input signal)
   TIOCM_CTS   Clear To Send (input signal)


TIOCMBIS   enable modem control signals
---------------------------------------
   int sigs = TIOCM_RTS | TIOCM_DTR
   rc = ioctl(fd, TIOCMBIS, &sigs);

Enable modem control signals specified by sigs argument.
Enabled signals are indicated with the following bit definitions,
with other signals left in the current state:

   TIOCM_RTS   Request To Send (output signal)
   TIOCM_DTR   Data Terminal Ready (output signal)


TIOCMBIC   disable modem control signals
----------------------------------------
   int sigs = TIOCM_RTS | TIOCM_DTR
   rc = ioctl(fd, TIOCMBIC, &sigs);

Disable modem control signals specified by sigs argument.
Disabled signals are indicated with the following bit definitions,
with other signals left in the current state:

   TIOCM_RTS   Request To Send
   TIOCM_DTR   Data Terminal Ready


TIOCMSET   set modem control signal states
------------------------------------------

   int sigs = TIOCM_RTS | TIOCM_DTR
   rc = ioctl(fd, TIOCMSET, &sigs);

Set state of modem control signals specified by sigs argument.
Enabled signals are indicated with the following bit definitions,
other signals are disabled.
For additional signals (LL&RL) see SEAMAC_IOCTL_SSIGNALS

   TIOCM_RTS   Request To Send
   TIOCM_DTR   Data Terminal Ready


TIOCMIWAIT - wait for serial status signals to change
(NOTE: This event is not applicable for most SeaMAC hardware)
-----------------------------------------------------

   int sigs = TIOCM_RNG | TIOCM_DSR | TIOCM_CD | TIOCM_CTS;
   rc = ioctl(fd, TIOCMGET, sigs);

Wait for one or more serial status signals to change. Specify signals
of interest with the following bit definitions:

   TIOCM_CAR   Data Carrier Detect
   TIOCM_RNG   Ring Indicator
   TIOCM_DSR   Data Set Ready
   TIOCM_CTS   Clear To Send

On return, the application should use ioctl(TIOCGICOUNT)
(Get Input Counts) to see which signal(s) changed.


TIOCGICOUNT - get count of serial status signal changes
-------------------------------------------------------

   struct serial_icounter_struct icount;
   rc = ioctl(fd, TIOCGICOUNT, &icount);

Return a serial_icounter_struct structure with counts of serial
status signal changes and line errors.

serial_icounter_struct is typically found in
/usr/include/linux/serial.h and is defined as:

   struct serial_icounter_struct {
      int cts, dsr, rng, dcd;
      int rx, tx;
      int frame, overrun, parity, brk;
      int buf_overrun;
      int reserved[9];
   };

   cts             number of interrupt transitions in Clear to Send (CTS).
   dsr             number of interrupt transitions in Data Set Ready (DSR).
   rng             number of interrupt transitions in Ring Indicator (RI).
   dcd             number of interrupt transitions in Data Carrier Detect (DCD).
   rx              number of received asynchronous data bytes.
   tx              number of transmitted asynchronous data bytes.
   frame           number of asynchronous framing errors or SDLC CRC errors detected.
   overrun         number of asynchronous receive overruns detected.
   parity          number of asynchronous parity errors detected.
   brk             number of asynchronous break sequences detected.
   buf_overrun     number of times the driver's receive data buffer overflowed.


TIOCOUTQ - get count of pending send data
-----------------------------------------
   int count;
   rc = ioctl(fd, TIOCOUTQ, &count);

Returns a byte count of pending send data. This can be used to
poll a device for send completion. When rc is zero, all data
has been sent.


SEAMAC_IOCTL_GSECURITY - get the factory programmed port security key
---------------------------------------------------------------------
   unsigned int security;
   rc = ioctl(fd, SEAMAC_IOCTL_GSECURITY, &security);

Returns the factory-programmed security key for the specified port.
This value can be used by the application to authenticate the
hardware.  The default value is 0x0000FFFF.


SEAMAC_IOCTL_GSIGNALS - get a mask of active modem control signals
------------------------------------------------------------------
   unsigned int signals;
   rc = ioctl(fd, SEAMAC_IOCTL_GSIGNALS, &signals);

Returns a bitmaps indicating the current modem control signal statuses.
This method is similar to the built-in termios TIOCMGET ioctl call
with additional custom signals represented.  All signals use positive
logic.

See SEAMAC_IOCTL_SSIGNALS for bit-mask values.


SEAMAC_IOCTL_SSIGNALS - sets the state of output modem control signals
----------------------------------------------------------------------
   unsigned int signals = SEAMAC_RTS | SEAMAC_DTR ....;
   rc = ioctl(fd, SEAMAC_IOCTL_SSIGNALS, &signals);

Sets the output states of the specified modem control signals.  This
method is similar to the built-in termios TIOCMSET ioctl call with
support for additional custom signals.  All signals use positive logic.

   SEAMAC_RTS   OUT   Request To Send
   SEAMAC_DTR   OUT   Data Terminal Ready
   SEAMAC_RL    OUT   Remote Loopback
   SEAMAC_LL    OUT   Local Loopback
   SEAMAC_CTS   IN    Clear To Send 
   SEAMAC_DCD   IN    Data Carrier Detect
   SEAMAC_DSR   IN    Data Set Ready


SEAMAC_IOCTL_HUNT - enter synchronization hunt mode
---------------------------------------------------
   rc = ioctl(fd, SEAMAC_IOCTL_HUNT);

Sends a command to the hardware that enables synchronization hunt mode.  Hunt
mode places the receiver in an idle state and stops all character assembly until
the synchronization method is matched.  In Monosync and Bisync modes, this
consists of matching the sync flag(s) in the incoming data stream.  In External
Sync mode, this consists of stopping waiting until the SYNC pin (CTS) goes low.


SEAMAC_IOCTL_GTXACTIVE - check if transmission is active
--------------------------------------------------------

   int active;
   rc = ioctl(fd, SEAMAC_IOCTL_GTXACTIVE, &active);

Returns the transmission activity status in a logical int: zero if inactive,
nonzero if active.


SEAMAC_IOCTL_GPARAMS - get device configuration
-----------------------------------------------

   struct seamac_params params;
   rc = ioctl(fd, SEAMAC_IOCTL_GPARAMS, &params);

Returns the device configuration in a seamac_params structure.
See SEAMAC_IOCTL_SPARAMS for more information about the params structure.


SEAMAC_IOCTL_SPARAMS - set device configuration
-----------------------------------------------

   struct seamac_params params;
   params.mode = SEAMAC_MODE_SDLC;
   params.loopback = 0;
   // other application defined settings...

   rc = ioctl(fd, SEAMAC_IOCTL_SPARAMS, &params);

Set device configuration specified by seamac_params structure.

The seamac_params structure is defined in seamac.h:

   struct seamac_params {
	// Overall device configuration mode (further config is subset)
	unsigned char mode;

	// Electrical interface to use for this port - unused on ISA/PC-104
	unsigned char interface;

	// Enable/disable internal loopback
	unsigned char loopback;

	// This is the value of the oscillator... if you don't use a custom 
	// oscillator, you don't need to change this value
	unsigned int baseclk;

	// The desired data rate in bits/second (will be overwritten with closest achievable)
	unsigned int rate;

	// Sync modes - clk can be encoded in the signal to cut down on wiring
	unsigned char encoding;

	// The clk for each signal can come from 4 different places
	unsigned char txclk;
	unsigned char rxclk;

	// It could be helpful to wire an oscillator directly to the rxclk
	unsigned char rxclktype;

	// What should the port echo back out on the telement line?
	unsigned char telement;

	// Async - Number of stop bits
	unsigned char stopbits;

	// Primarily Async - Type of parity
	unsigned char parity;

	// How many bits per character for DATA?
	unsigned char txbits;
	unsigned char rxbits;

	// Monosync/bisync flag.  8 or 16 bits depending on mode (l.s.B is flag)
	unsigned short syncflag;
	
	// The size of the flag can be modified to 6 or 12 (based on mode)
	unsigned char sixbitflag;

	// The device can filter messages based on the addr field
	unsigned char addrfilter;
	
	// Or it can just filter a range of 16 addresses
	unsigned char addrrange;

	// Only selectable in non SDLC mode
	unsigned char crctype;

	// The CRC can be preset to a value of 0 or 1
	unsigned char crcpreset;

	// The device can either idle 1's or flags
	unsigned char idlemode;

	// Custom idle patter (for supported devices, idlemode = CUSTOM)
	unsigned short idlepattern;

	// Control what happens on a tx underrun condition
	unsigned char underrun;

	// Hardware flow control options
	unsigned char handshaking;

	// Automatic RTS control during TX by driver
	unsigned char rtscontrol;
	
	// Delay (ms) before TX to allow bus to settle, useful for slower 
	// remote devices that require RTSCONTROL
	unsigned short pretxdelay;

	// Delay (ms) after TX to allow bus to settle, useful for slower 
	// remote devices that require RTSCONTROL
	// This can also be used to delay transmitter deactivation to allow
	// closing flags to be transmitted
	unsigned short posttxdelay;
   };


   mode        Communications mode/protocol.

               SEAMAC_MODE_ASYNC  character oriented, no external clocks
                                   per character hardware framing
                                   per character parity check (none/even/odd)

               SEAMAC_MODE_SDLC   bit synchronous
                                   hardware framing and synchronization (flags)
                                   hardware transparency (0 bit stuff/removal)
                                   hardware CRC check/generation (ccitt only)

               SEAMAC_MODE_MONOSYNC   byte synchronous
	       			   hardware start of frame and synchronization
				   one byte for sync flag
				   device driver WILL NOT end frame

               SEAMAC_MODE_BISYNC    byte synchronous
	       			   hardware start of frame and synchronization
				   two bytes for sync flag
				   device driver WILL NOT end frame

               SEAMAC_MODE_BISYNC_FRAMED    byte synchronous
				   hardware receive synchronization is automatic (0x5C5C)
				   transmit data is completely raw
				   custom 9198 hardware only

               SEAMAC_MODE_EXTERNAL  byte synchronous
	                           external signal (CTS) triggers synchronization
				   device driver WILL NOT end frame

               SEAMAC_MODE_EXTERNAL_RTS  byte synchronous
	                           external signal (RTS) triggers synchronization
				   device driver WILL NOT end frame


   interface   This parameter is used to set the device's electrical interface.
               Setting this feature is not available in all models - check your
               device manual.

               SEAMAC_IF_HWSELECT Non-selectable mode.  This is simply an
                                  identifier returned if the given device is
                                  one the driver knows does not have a software
                                  selectable interface.

               SEAMAC_IF_OFF     Disable the electrical interface by putting all
                                  signals in a state of high impedance.

               SEAMAC_IF_232     RS-232 is capable of operating at data rates
                                  up to 20 Kbps at distances less than 50 ft.
                                  The absolute maximum data rate may vary due to
                                  line conditions and cable lengths. RS-232
                                  often operates at 38.4 Kbps over very short
                                  distances. The voltage levels defined by
                                  RS-232 range from -12 to +12 volts. RS-232 is
                                  a single ended or unbalanced interface,
                                  meaning that a single electrical signal is
                                  compared to a common signal (ground) to
                                  determine binary logic states. A voltage of
                                  +12 volts (usually +3 to +10 volts) represents
                                  a binary 0 (space) and -12 volts 
                                  (-3 to -10 volts) denotes a binary 1 (mark).

               SEAMAC_IF_485     RS-485 is backwardly compatible with RS-422;
               SEAMAC_IF_485E     however, it is optimized for partyline or
                                  multi-drop applications. The output of the
                                  RS-422/485 driver is capable of being Active
                                  (enabled) or Tri-State (disabled). This 
                                  capability allows multiple ports to be
                                  connected in a multi-drop bus and selectively
                                  polled. RS-485 allows cable lengths up to 4000
                                  feet and data rates up to 10 Megabits per
                                  second. The signal levels for RS-485 are the
                                  same as those defined by RS-422.  By default,
				  the receiver sees all data transmitted.  This
				  creates and "echo" effect.  The echo can be
				  automatically filtered from the receiver by
				  using the IF_485E mode.
               
               SEAMAC_IF_485T    This is the same as RS485_NOTERM, except there
               SEAMAC_IF_485TE    is a resistance placed between the + and -
                                  lines.  This mode of operation is required to
                                  maintain line conditions in a multidrop
                                  network on both the first and last devices.
                                  For example if you have 9 devices, device 0
                                  and device 8 should enable RS485_TERM.
                                  By default, the receiver sees all data 
				  transmitted.  This creates and "echo" effect. 
				  The echo can be automatically filtered from 
				  the receiver by using the IF_485TE mode.
                                  T===NT===NT===NT===NT===NT===NT===NT===T
                                  0    1    2    3    4    5    6    7   8

               SEAMAC_IF_422     RS-530 (a.k.a. EIA-530) compatibility means
               SEAMAC_IF_530      that RS-422 signal levels are met, and the
                                  pin-out for the DB-25 connector is specified.
                                  The EIA (Electronic Industry Association) 
                                  created the RS-530 specification to detail
                                  the pin-out, and define a full set of modem 
                                  control signals that can be used for 
                                  regulating flow control and line status.
                                  The Sealevel adapter is a DTE interface.


               SEAMAC_IF_530A    The major difference between RS-530 and 
                                  RS-530A lies in some of the modem control
                                  interface signals. In RS-530 the signals all
                                  of the modem control signals are differential,
                                  in RS-530A some of these signals are single 
                                  ended.

               SEAMAC_IF_V35     ITU V.35 electrical characteristics are a
                                  combination of unbalanced voltage and balanced
                                  current mode signals. Data and clock signals
                                  are balanced current mode circuits. These
                                  circuits typically have voltage levels from 
                                  0.5 Volts to -0.5 Volts (1 Volt differential).
                                  The modem control signals are unbalanced
                                  signals and are compatible with RS-232.


   baseclk     This value is used by the driver to calculate the time constant
               necessary to achieve a data rate given by the "rate" parameter.
               The baseclk is set to a default based on the physical oscillators
               that each device is given.
               
               SEAMAC_ISA_CLK    The default oscillator frequency for ISA/PC-104
                                  devices is 7.3728 MHz.

               SEAMAC_PCI_CLK    The default oscillator frequency for PCI
                                  devices is also 7.3728 MHz.

               SEAMAC_PCMCIA_CLK The default oscillator frequency for PCMCIA
                                  devices is 14.7456 MHz.
               
               These values are the default oscillator frequencies, if you use
               a custom oscillator you should input that value through this
               parameter.
 
 
   rate        Data rate of generated clock.
                 0 = disable clock generation and DPLL clock recovery

               The clock is generated by dividing the baseclk frequency
               by an integer called the time constant. The time
               constant is related to the data rate by:

               Time Constant = ((baseclk / (2 * bps)) - 2)
               (note that in Async mode, the baseclk is internally divided by
                16, making the maximum achievable baudrate a little lower)

               If the calculated time constant for a particular speed is
               an integer (or zero) then the specified data rate can be
               generated exactly. Otherwise the actual data rate is the
               data rate specified by the time constant rounded up to the
               next integer value. For relatively low non standard data
               rates, the resulting error will be small. The clock
               frequency allows common data rate to be specified exactly:
               2400, 9600, 57600, 115200 etc.

               If your required data rate cannot be achieved with the default
               baseclk avaialable, Sealevel can modify the device with an appropriate
               oscillator.  If you are using a custom oscillator, the baseclk value
               should be modified in order for the rate calculation to be performed
               properly.  Contact Sealevel for further assistance.


   loopback    If non-zero, transmit data is looped back internally to
               receive data. Loopback mode is useful for diagnostics.


   encoding    Encoding determines how the TxD and RxD pins
               represent data bits or logical 1s and 0s.

               SEAMAC_ENCODE_NRZ          No encoding,
                                          high = 1, low = 0.

               SEAMAC_ENCODE_NRZI         Invert state at start of bit
                                          cell for a 0, maintain state for
                                          a 1.

               SEAMAC_ENCODE_FM0          Always invert state at start of
                                          bit cell. Invert in middle of
                                          bit cell if 0, maintain state if 1.

               SEAMAC_ENCODE_FM1          Always invert state at start of
                                          bit cell. Invert in middle of
                                          bit cell if 1, maintain state if 0.
                                          Used with DPLL clock recovery.


   txclk       Determine clock source.  The transmit and receive clock sources
   rxclk       can be set to come from 1 of 4 different places.
               
               SEAMAC_CLK_RXCLK           The given clock is taken from the
                                          RxClk Input Pin.

               SEAMAC_CLK_TXCLK           The given clock is taken from the
                                          TxClk Input Pin.

               SEAMAC_CLK_BRG             The given clock is generated
                                          by the onboard baud rate generator
                                          at the speed specified in the rate
                                          member of the seamac_params structure.

               SEAMAC_CLK_DPLL            The given clock is recovered from
                                          the DPLL. The DPLL reference
                                          frequency is specified in the
                                          rate member of the
                                          seamac_params structure.


   rxclktype   The receive clock type.  The receive clock pin can accept two
               type of input clocks: TTL and Crystal Oscillator.  If it is
               advantageous to supply a Crystal Oscillator directly to the
               rxclkpin to achieve a desired data rate, it can be done using
               this member of the seamac_params structure.

               SEAMAC_RXCLK_TTL           The clock signal routed to the RxClk
                                          pin is expected to be a TTL signal.
               SEAMAC_RXCLK_XTAL          A crystal oscillator clock signal is
                                          expected on the RxClk pin.

   telement    The clock source for the Timing Element pin.  The TELEMENT pin
               can have a number of sources.
               
               SEAMAC_TELEMENT_XTAL       The onboard crystal oscillator.
               SEAMAC_TELEMENT_TXCLK      The clock used for transmission.
               SEAMAC_TELEMENT_BRG        The onboard baud rate generated clock.
               SEAMAC_TELEMENT_DPLL       The recovered clock from the DPLL.


   stopbits    The number of bit times to indicate end of frame in Async mode.

               SEAMAC_STOP_1              The standard single bit time.
               SEAMAC_STOP_1_5            One and 1/2 bit times.
               SEAMAC_STOP_2              Two bit times.


   parity      An extra bit can be added to indicate the parity of a byte of
               data.  This can be used to verify data integrity at a very basic
               level.
               
               SEAMAC_PARITY_NONE         Disable parity detection/generation.
               SEAMAC_PARITY_EVEN         Enable even parity detection/
                                          generation.
               SEAMAC_PARITY_ODD          Enable odd parity detection/
                                          generation.


   txbits      The number of bits per character can be set for both transmit
   rxbits      and receive.

               SEAMAC_BITS_8              The default 8 bits/character.
               SEAMAC_BITS_7              7 bits/character.
               SEAMAC_BITS_6              6 bits/character.
               SEAMAC_BITS_5              5 bits/character.


   syncflag    Two bytes for use in Monosync and Bisync modes.  In Monosync
               mode, only the low byte of syncflag is used.


   sixbitflag  When operating in Monosync mode, it may be desirable to use
               a six bit sync flag rather than 8.  Note that this also applies
	       to Bisync mode using a 12 bit flag rather than 16.


   addrfilter  Discard received SDLC frames with addresses other than
               0xFF (broadcast) or addrfilter value. If addrfilter is
               0xFF then no filtering is done.


   addrrange   Expand the range of accepted addresses by 16.  This is achieved
               by ignoring the lower 4 bits of the addrfilter.  Any non zero
               value will activate this mode.


   crctype     SDLC Hardware Cyclic Redundancy Check.  Note: hardware crc
               generation/checking is not supported in any other mode of 
	       operation, but may be added by user software.

               SEAMAC_CRC_CCITT          16 bit SDLC CRC polynomial.


   crcpreset   The CRC generator/checker can be preset to a value of 0 or 1.

               SEAMAC_CRCPRESET_0        Preset to 0.
               SEAMAC_CRCPRESET_1        Preset to 1.


   idlemode    Idle line state.
   
               SEAMAC_IDLE_FLAG          Idle sync flags.
               SEAMAC_IDLE_ONES          Idles ones.
	       SEAMAC_IDLE_CUSTOM	 Idle custom pattern (custom hardware only)


   idlepattern Custom 16-bit idle pattern.


   underrun    What to do when TX Fifo is empty.  Only applicable in SDLC mode.
   
               SEAMAC_UNDERRUN_ABORT     Send the CRC (if applicable) followed
                                         by an abort sequence.
               SEAMAC_UNDERRUN_FLAG      Send the CRC (if applicable) followed
                                         by a sync flag.

   handshaking Hardware flow control (custom hardware only)

	       SEAMAC_HANDSHAKE_NONE	 No hardware flow control
	       SEAMAC_HANDSHAKE_RTSCTS	 RTS/CTS handshaking protocol


   rtscontrol  Automatic RTS control by driver during data TX.

               SEAMAC_RTSCONTROL_DISABLE No automatic control.  RTS is 
                                         controlled only by the user.
               SEAMAC_RTSCONTROL_TOGGLE  The driver will automatically enable
                                         RTS before TX and disabled after.

   pretxdelay  Artificial delay before TX but after automatic RTS toggling.
               This value is expressed in ms.  The maximum is delay is 65535.

   posttxdelay Artificial delay after TX but before automatic RTS toggling.
               This value is expressed in ms.  The maximum is delay is 65535.
	       Note: If using RTS for TX/RX enable, it is necessary to make
	       this delay at least one character time.  Due to constraints in
	       the hardware, it is impossible for the driver to determine when
	       the final character has been completely transmitted.  The driver
	       will simply drop RTS when the 4B FIFO has been emptied, meaning
	       there is still at least one character being transmitted.  If you
	       need CRC (SDLC only) then an additional two character times are
	       required.  If a closing flag is required one or two other
	       character times should be added.  Due to the possibility of the
	       TX clock being supplied by the remote device, it is impossible
	       for the driver to add appropriate delays, so it is necessary
	       for the user to provide the proper delay times depending on the
	       application requirements.

DPLL Clock Recovery
===================

Synchronous modes usually get transmit and receive timing from
the transmit and receive clock inputs.

Alternatively, timing can be recovered from a data signal
using a digital phased locked loop (DPLL). DPLL clock recovery
requires the exact data rate to be known in advance.  A data signal
using NRZI mode requires a DPLL input clock of 32X the data rate you wish
to recover.  So, if the data rate you wish to use is 1000 bps, the BRG of
the recovering device must be set to 32000 bps.  Similarly, the BRG must
be set 16X the expected data rate for FMX encoding recovery.

Please be sure that the data rate you wish to use, can be multiplied by
32 or 16 on the secondary device.  This may require use of a custom oscillator,
or a lower data rate.

 // Master device
 master.rate =      76800;
 master.encoding =  SEAMAC_ENCODE_FM0;
 master.txclk =     SEAMAC_CLK_BRG;
 master.rxclk =     SEAMAC_CLK_DPLL;
 ...

 // Slave device 
 slave.rate =      1228800;  //16X expected FM (32X in NRZI)
 slave.encoding =  SEAMAC_ENCODE_FM0;
 slave.txclk =     SEAMAC_CLK_DPLL;
 slave.rxclk =     SEAMAC_CLK_DPLL;
 ...

Please see the sample-sdlc-encoded/ directory for a clock encoding sample
application.


ASYNCHRONOUS COMMUNICATIONS
===========================

When a Seamac adapter is configured for asynchronous mode,
all programming can be done with the standard Linux systems calls
and tty/termios functions. In this mode, the Seamac device
operates the same as any other serial port.  Note that this means custom
settings that aren't achievable through the standard tty/termios functions
will be reset when the port is closed and then re-opened.  This happens
because the termios structure cannot save the custom settings set by the
Seamac ioctls, and the settings last saved in the port's termios structure
override those last set by the ioctl on port open().  Refer to Linux
documentation and third party books on the subject of
serial device programming and termios functions for details.


N_TTY line discipline
=====================

This is a brief caveat regarding the default N_TTY line discipline.  This
ldisc is designed with terminal/console emulation in mind, and it therefore
has many extra features to facilitate these modes of operation.  These extra
features take liberties with incoming data and attempt to interpret it as
console/terminal commands, sometimes even automatically sending responses.

These features can cause havoc with custom data protocols when a SeaMAC device
is used in any mode other than SDLC (uses the N_HDLC line discipline).  If
odd things are happening when formatting raw data, ensure that the N_TTY line
discipline is not causing the problem.

Example:
   rc = tcgetattr(fd, &termios);

   termios.c_iflag = 0;
   termios.c_oflag = 0;
   termios.c_cflag = CREAD | CS8 | HUPCL | CLOCAL;
   termios.c_lflag = 0;
   termios.c_cc[VTIME] = 0;
   termios.c_cc[VMIN]  = 1;

   rc = tcsetattr(fd, TCSANOW, &termios);

