su(7D)




NAME

     su - asynchronous serial port driver


SYNOPSIS

     #include <fcntl.h>
     #include <sys/termios.h>
     open("/dev/tty[a-z]", _mode);
     open("/dev/term[a-z]", _mode);
     open("/dev/cua[a-z]", _mode);


DESCRIPTION

     The su module is a loadable  STREAMS  driver  that  provides
     basic  support  for  standard  UARTS  that  use  Intel-8250,
     National Semiconductor-16450/16550 hardware and  Southbridge
     1535D (16550 compatable) Super I/O hardware. The module also
     provides keyboard and mouse I/O  support  for  Sun  machines
     using  those  same  Intel, National Semiconductor and South-
     bridge chipsets. The su driver provides  basic  asynchronous
     communication support for serial ports. Both the serial dev-
     ices and keyboard/mouse devices will have streams built with
     appropriate  modules  pushed atop the  su driver by means of
     either the autopush(1M) or dacf.conf(4) facilities,  depend-
     ing on the OS revision and architecture in use.

     The su module supports those termio(7I) device control func-
     tions  specified by flags in the c_cflag word of the termios
     structure, and by the IGNBRK, IGNPAR, PARMRK, or INPCK flags
     in  the  c_iflag  word  of the termios structure.  All other
     termio(7I) functions must be performed  by  STREAMS  modules
     pushed  atop  the  driver.   When  a  device  is opened, the
     ldterm(7M) and ttcompat(7M) STREAMS  modules  are  automati-
     cally  pushed  on  top of the stream, providing the standard
     termio(7I) interface.

     The character-special devices /dev/ttya  and  /dev/ttyb  are
     used  to access the two standard serial ports. The su module
     supports up to ten  serial  ports,  including  the  standard
     ports. The tty[a-z] devices have minor device numbers in the
     range  00-03,  and  may  be  assigned  names  of  the   form
     /dev/ttyd_n_,  where  _n_  denotes  the line to be accessed.
     These device names are typically used to provide  a  logical
     access point for a _dial-in_ line that is used with a modem.

     To allow a single tty line to be connected to  a  modem  and
     used  for  incoming and outgoing calls, a special feature is
     available that is controlled by the minor device number.  By
     accessing  character-special  devices with names of the form
     /dev/cua_n, it is possible to open a port without  the  Car-
     rier  Detect  signal being asserted, either through hardware
     or an equivalent software mechanism. These devices are  com-
     monly known as _dial-out_ lines.


APPLICATION PROGRAMMING INTERFACE

     Once a /dev/cua_n_ line is opened, the corresponding tty, or
     ttyd  line  cannot  be  opened until the /dev/cua_n_ line is
     closed. A blocking open will wait until the /dev/cua_n_ line
     is  closed (which will drop Data Terminal Ready, after which
     Carrier Detect will usually drop as  well)  and  carrier  is
     detected again. A non-blocking open will return an error. If
     the /dev/ttyd_n_ line has been opened successfully  (usually
     only   when   carrier  is  recognized  on  the  modem),  the
     corresponding /dev/cua_n_ line cannot be opened. This allows
     a   modem   to  be  attached  to  a  device,  (for  example,
     /dev/ttyd0, which is renamed from /dev/tty00) and  used  for
     dial-in  (by enabling the line for login in /etc/inittab) or
     dial-out (by tip(1) or uucp(1C)) as /dev/cua0 when no one is
     logged in on the line.


IOCTLS

     The standard set of termio ioctl() calls  are  supported  by
     su.

     Breaks  can  be  generated  by  the  TCSBRK,  TIOCSBRK,  and
     TIOCCBRK ioctl() calls.

     The input and output line speeds may be set to  any  of  the
     following  baud  rates:  0, 50, 75, 110, 134, 150, 200, 300,
     600,   1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600  or
     115200. The speeds cannot be set independently; for example,
     when the output speed is set, the input speed  is  automati-
     cally set to the same speed.

     When the  su module is used to service  the  serial  console
     port,  it  supports a BREAK condition that allows the system
     to enter the debugger or the monitor. The BREAK condition is
     generated by hardware and it is usually enabled by default.

     A BREAK condition originating from erroneous electrical sig-
     nals  cannot  be distinguished from one deliberately sent by
     remote DCE. The Alternate Break sequence can be  used  as  a
     remedy  against  this.  Due  to a risk of incorrect sequence
     interpretation, binary protocols such as PPP, SLIP, and oth-
     ers  should  not  be  run  over the serial console port when
     Alternate Break sequence  is  in  effect.  By  default,  the
     Alternate Break sequence is a three character sequence: car-
     riage return, tilde and control-B (CR ~ CTRL-B), but may  be
     changed  by  the  driver.  For  more information on breaking
     (entering the debugger or monitor), see kbd(1) and kb(7M).


ERRORS

     An open() will fail under the following conditions:

          ENXIO The unit being opened does not exist.

          EBUSY The dial-out device is  being  opened  while  the
                dial-in  device  is  already open, or the dial-in
                device is being opened with a no-delay  open  and
                the dial-out device is already open.

          EBUSY The unit has  been  marked  as  exclusive-use  by
                another process with a TIOCEXCL ioctl() call.


FILES

     /dev/cua/[a-z]
           dial-out tty lines

     /dev/term/[a-z]
           dial-in tty lines

     /dev/tty[a-z]
           binary compatibility package device names


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                |  SPARC                      |
    |_____________________________|_____________________________|


SEE ALSO

     strconf(1),    kbd(1),    tip(1),uucp(1C),     autopush(1M),
     kstat(1M),  ioctl(2),  open(2),  termios(3C),  dacf.conf(4),
     attributes(5), kb(7M), ldterm(7M), ttcompat(7M), termio(7I)


DIAGNOSTICS

     The su driver keeps track of various warning and error  con-
     ditions  using  kstat  counters.  The output of the kstat su
     command provides kstat  counters.  The  counters  and  their
     meaning follow:

     silo overflow
           The internal chip FIFO  received  more  data  than  it
           could handle. This indicates  that the Solaris operat-
           ing environment was not servicing data interrupts fast
           enough  possibly  due to a system with too many inter-
           rupts or a data line with a  data  rate  that  is  too
           high.

     ring buffer overflow
           The su module was unable to  store   data  it  removed
           from  the  chips internal FIFO into a software buffer.
           The user process is not reading data fast enough, pos-
           sibly  due  to an overloaded system. If  possible, the
           application should enable flow control (either  CTSRTS
           or  XONXOFF)  to  allow the driver to backpressure the
           remote system when the local buffers fill up.


Man(1) output converted with man2html