SETSERIAL(8)                                         SETSERIAL(8)

NAME
       setserial - get/set Linux serial port information

SYNOPSIS
       setserial [ -abqvVWz ] device [ parameter1 [ arg ] ] ...

       setserial -g [ -abGv ] device1 ...

DESCRIPTION
       setserial  is  a program designed to set and/or report the
       configuration information associated with a  serial  port.
       This information includes what I/O port and IRQ a particu-
       lar serial port is using, and whether or not the break key
       should  be interpreted as the Secure Attention Key, and so
       on.

       During the normal bootup process, only COM ports  1-4  are
       initialized,  using  the default I/O ports and IRQ values,
       as listed below.  In order to  initialize  any  additional
       serial  ports,  or  to  change the COM 1-4 ports to a non-
       stadard configuration, the  setserial  program  should  be
       used.   Typically  it  is called from an rc.serial script,
       which is usually run out of /etc/rc.local.

       The device argument  or  arguments  specifies  the  serial
       device  which  should  be  configured or interrogated.  It
       will usually have the following form: /dev/cua[0-3].

       If no parameters are specified, setserial will  print  out
       the  port  type  (i.e., 8250, 16450, 16550, 16550A, etc.),
       the hardware I/O port, the hardware IRQ  line,  its  "baud
       base," and some of its operational flags.

       If  the -g option is given, the arguments to setserial are
       interpreted as a list of devices for which the  character-
       istics of those devices should be printed.

       Without  the -g option, the first argument to setserial is
       interpreted as the device to be modified  or  characteris-
       tics  to  be  printed,  and  any  additional arguments are
       interpreted as parameters which should be assigned to that
       serial device.

       For  the most part, superuser privilege is required to set
       the configuration parameters of  a  serial  port.   A  few
       serial  port  parameters  can be set by normal users, how-
       ever, and these will be noted as exceptions in this manual
       page.

OPTIONS
       Setserial accepts the following options:

       -a     When   reporting  the  configuration  of  a  serial
              device, print all available information.

       -b     When  reporting  the  configuration  of  a   serial
              device,  print a summary of the device's configura-
              tion, which might be suitable for  printing  during
              the bootup process, during the /etc/rc script.

       -G     Print  out  the  configuration  information  of the
              serial port in a form which can be fed back to set-
              serial as command-line arguments.

       -q     Be quiet.  Setserial will print fewer lines of out-
              put.

       -v     Be verbose.  Setserial will print additional status
              output.

       -V     Display version and exit.

       -W     Do  wild  interrupt  initialization and exit.  This
              option is no longer relevant in Linux kernels after
              version 2.1.

       -z     Zero  out  the  serial flags before starting to set
              flags.  This is related to the automatic saving  of
              serial flags using the -G flag.

PARAMETERS
       The following parameters can be assigned to a serial port.

       All argument values are assumed to be  in  decimal  unless
       preceeded by "0x".

       port port_number
              The  port  option  sets  the I/O port, as described
              above.

       irq irq_number
              The irq option sets the hardware IRQ, as  described
              above.

       uart uart_type
              This option is used to set the UART type.  The per-
              mitted types are none, 8250, 16450, 16550,  16550A,
              16650,  16650V2,  and  16750.   Since  the 8250 and
              16450 UARTS do not have FIFO's, and since the orig-
              inal  16550  have  bugs which make the FIFO's unus-
              able, the FIFO will only be used on chips identifi-
              ied  as  16550A  UARTs.   Setting  the UART type to
              8250, 16450, or 16550 will enable the  serial  port
              without  trying  to  use  the FIFO. Using UART type
              none will disable the port.

              Some internal modems are billed as having a "16550A
              UART  with  a  1k buffer".  This is a lie.  They do
              not have really  have  a  16550A  compatible  UART;
              instead  what  they have is a 16450 compatible UART
              with a 1k receive buffer to prevent receiver  over-
              runs.   This is important, because they do not have
              a transmit FIFO.  Hence, they  are  not  compatible
              with  a 16550A UART, and the autoconfiguration pro-
              cess will correctly identify them as  16450's.   If
              you attempt to override this using the uart parame-
              ter, you will see dropped  characters  during  file
              transmissions.   These  UART's  usually  have other
              problems: the skip_test parameter also  often  must
              be specified.

       autoconfig
              When  this  parameter  is given, setserial will ask
              the kernel to attempt  to  automatically  configure
              the  serial  port.   The I/O port must be correctly
              set; the kernel will attempt to determine the  UART
              type,  and  if the auto_irq parameter is set, Linux
              will attempt to automatically  determine  the  IRQ.
              The  autoconfig parameter should be given after the
              port,auto_irq, andskip_test  parameters  have  been
              specified.

       auto_irq
              During autoconfiguration, try to determine the IRQ.
              This feature is not guaranteed  to  always  produce
              the  correct  result;  some hardware configurations
              will fool the Linux kernel.  It is generally  safer
              not  to  use  the  auto_irq  feature, but rather to
              specify the IRQ to be used  explicitly,  using  the
              irq parameter.

       ^auto_irq
              During  autoconfiguration,  do not try to determine
              the IRQ.

       skip_test
              During autoconfiguration, skip the UART test.  Some
              internal  modems do not have National Semiconductor
              compatible  UART's,  but  have   cheap   imitations
              instead.  Some of these cheasy imitations UART's do
              not fully  support  the  loopback  detection  mode,
              which  is  used  by  the  kernel to make sure there
              really is a UART at  a  particular  address  before
              attempting  to configure it.  So for certain inter-
              nal modems you will need to specify this  parameter
              so Linux can initialize the UART correctly.

       ^skip_test
              During  autoconfiguration,  do  not  skip  the UART
              test.

       baud_base baud_base
              This option sets the base baud rate, which  is  the
              clock frequency divided by 16.  Normally this value
              is 115200, which is  also  the  fastest  baud  rate
              which the UART can support.

       spd_hi Use  57.6kb  when  the application requests 38.4kb.
              This parameter may be specified by a non-privileged
              user.

       spd_vhi
              Use  115kb  when  the  application requests 38.4kb.
              This parameter may be specified by a non-privileged
              user.

       spd_cust
              Use  the  custom  divisor to set the speed when the
              application requests 38.4kb.   In  this  case,  the
              baud  rate is the baud_base divided by the divisor.
              This parameter may be specified by a non-privileged
              user.

       spd_normal
              Use  38.4kb  when  the application requests 38.4kb.
              This parameter may be specified by a non-privileged
              user.

       divisor divisor
              This  option sets the custom divison.  This divisor
              will be used then the spd_cust option  is  selected
              and  the serial port is set to 38.4kb by the appli-
              cation.  This parameter may be specified by a  non-
              privileged user.

       sak    Set the break key at the Secure Attention Key.

       ^sak   disable the Secure Attention Key.

       fourport
              Configure the port as an AST Fourport card.

       ^fourport
              Disable AST Fourport configuration.

       close_delay delay
              Specify the amount of time, in hundredths of a sec-
              ond, that DTR should remain low on  a  serial  line
              after  the  callout  device  is  closed, before the
              blocked  dialin  device  raises  DTR  again.    The
              default  value of this option is 50, or a half-sec-
              ond delay.

       closing_wait delay
              Specify the amount of time, in hundredths of a sec-
              ond,  that  the  kernel  should wait for data to be
              transmitted from the serial port while closing  the
              port,  before  the  receiver has been disabled.  If
              "none" is specified, no delay will occur. If "infi-
              nite"  is  specified  the  kernel will wait indefi-
              nitely  for the buffered data  to  be  transmitted.
              The default setting of is "none".

       closing_wait2 delay
              Specify the amount of time, in hundredths of a sec-
              ond, that the kernel should wait  for  data  to  be
              transmitted  from the serial port while closing the
              port, after the receiver  has  been  disabled.   As
              with  the  closing_wait  command,  both  "none" and
              "infinite" may be specified.  The  default  setting
              is 3000, or 30 seconds of delay.

              The  default  settings  of  closing_wait  and clos-
              ing_wait2  are  generally  appropriate   for   most
              devices.  If too long a delay is selected, then the
              serial port may hang for a  long  time  if  when  a
              serial  port  which  is not connected, and has data
              pending, is  closed.   If  too  short  a  delay  is
              selected,  then  there  is  a risk that some of the
              transmitted data is output at all.

              If the device is extremely slow,  like  a  plotter,
              the  values  of  closing_wait  or closing_wait2 may
              need to be extended further.

              If the device typically uses XON/XOFF  handshaking,
              the   default  values  of  closing_wait  and  clos-
              ing_wait2 should be reversed.  This has a danger of
              not  supressing  "echo  wars"  between Linux and an
              echoing modem, however.

       session_lockout
              Lock out callout port (/dev/cuaXX) accesses  across
              different  sessions.   That  is, once a process has
              opened a port, do not allow a process with  a  dif-
              ferent session ID to open that port until the first
              process has closed it.

       ^session_lockout
              Do not lock out callout port accesses  across  dif-
              ferent sessions.

       pgrp_lockout
              Lock  out callout port (/dev/cuaXX) accesses across
              different process groups.  That is, once a  process
              has opened a port, do not allow a process in a dif-
              ferent process group to open that  port  until  the
              first process has closed it.

       ^pgrp_lockout
              Do  not  lock out callout port accesses across dif-
              ferent process groups.

       hup_notify
              Notify a process blocked on opening a dial in  line
              when  a  process  has finished using a callout line
              (either by closing it or by the serial  line  being
              hung up) by returning EAGAIN to the open.

              The  application  of  this parameter is for getty's
              which are blocked on a serial port's dial in  line.
              This allows the getty to reset the modem (which may
              have had its configuration modified by the applica-
              tion  using  the callout device) before blocking on
              the open again.

       ^hup_notify
              Do not notify a process blocked on opening  a  dial
              in line when the callout device is hung up.

       split_termios
              Treat  the  termios  settings  used  by the callout
              device and the termios settings used by the  dialin
              devices as separate.

       ^split_termios
              Use  the  same  termios structure to store both the
              dialin and callout  ports.   This  is  the  default
              option.

       callout_nohup
              If this particular serial port is opened as a call-
              out device, do not  hangup  the  tty  when  carrier
              detect is dropped.

       ^callout_nohup
              Do  not  skip hanging up the tty when a serial port
              is opened as a  callout  device.   Of  course,  the
              HUPCL termios flag must be enabled if the hangup is
              to occur.

       ^low_latency
              Minimize the receive latency of the  serial  device
              at  the cost of greater CPU utilization.  (Normally
              there is an average of 5-10ms latency before  char-
              acters are handed off to the line discpline to min-
              imize overhead.)  This is off by default, but  cer-
              tain real-time applications may find this useful.

CONSIDERATIONS OF CONFIGURING SERIAL PORTS
       It  is  important  to note that setserial merely tells the
       Linux kernel where it should expect to find the  I/O  port
       and  IRQ lines of a particular serial port.  It does *not*
       configure the hardware, the actual serial board, to use  a
       particular  I/O  port.  In order to do that, you will need
       to physically program the serial board, usually by setting
       some jumpers or by switching some DIP switches.

       This  section  will  provide  some pointers in helping you
       decide how you would like to configure your serial  ports.

       The "standard MS-DOS" port associations are given below:

              /dev/ttys0 (COM1), port 0x3f8, irq 4
              /dev/ttys1 (COM2), port 0x2f8, irq 3
              /dev/ttys2 (COM3), port 0x3e8, irq 4
              /dev/ttys3 (COM4), port 0x2e8, irq 3

       Due  to  the  limitations  in the design of the AT/ISA bus
       architecture, normally an  IRQ  line  may  not  be  shared
       between  two  or  more serial ports.  If you attempt to do
       this, one or both serial ports will become  unreliable  if
       you  try  to use both simultaneously.  This limitation can
       be overcome by  special  multi-port  serial  port  boards,
       which  are  designed to share multiple serial ports over a
       single IRQ line.  Multi-port  serial  cards  supported  by
       Linux  include  the  AST FourPort, the Accent Async board,
       the  Usenet  Serial  II  board,  the  Bocaboard   BB-1004,
       BB-1008, and BB-2016 boards, and the HUB-6 serial board.

       The  selection  of  an  alternative IRQ line is difficult,
       since most of them are already used.  The following  table
       lists  the  "standard MS-DOS" assignments of available IRQ
       lines:

              IRQ 3: COM2
              IRQ 4: COM1
              IRQ 5: LPT2
              IRQ 7: LPT1

       Most people find that IRQ 5 is  a  good  choice,  assuming
       that  there  is  only one parallel port active in the com-
       puter.  Another good choice is IRQ 2 (aka IRQ 9); although
       this  IRQ  is  sometimes  used  by network cards, and very
       rarely VGA cards will be configured to use IRQ 2 as a ver-
       tical  retrace  interrupt.  If your VGA card is configured
       this way; try to disable it so you can  reclaim  that  IRQ
       line  for  some  other card.  It's not necessary for Linux
       and most other Operating systems.

       The only other available IRQ lines are 3, 4,  and  7,  and
       these  are  probably used by the other serial and parallel
       ports.  (If your serial card has a 16bit card edge connec-
       tor,  and  supports higher interrupt numbers, then IRQ 10,
       11, 12, and 15 are also available.)

       On AT class machines, IRQ 2 is seen as IRQ  9,  and  Linux
       will interpret it in this manner.

       IRQ's  other  than  2 (9), 3, 4, 5, 7, 10, 11, 12, and 15,
       should not be used, since they are assigned to other hard-
       ware  and  cannot,  in  general, be changed.  Here are the
       "standard" assignments:

              IRQ  0      Timer channel 0
              IRQ  1      Keyboard
              IRQ  2      Cascade for controller 2
              IRQ  3      Serial port 2
              IRQ  4      Serial port 1
              IRQ  5      Parallel port 2 (Reserved in PS/2)
              IRQ  6      Floppy diskette
              IRQ  7      Parallel port 1
              IRQ  8      Real-time clock
              IRQ  9      Redirected to IRQ2
              IRQ 10      Reserved
              IRQ 11      Reserved
              IRQ 12      Reserved (Auxillary device in PS/2)
              IRQ 13      Math coprocessor
              IRQ 14      Hard disk controller
              IRQ 15      Reserved

MULTIPORT CONFIGURATION
       Certain multiport serial boards which share multiple ports
       on  a single IRQ use one or more ports to indicate whether
       or not there are any pending ports which need to  be  ser-
       viced.   If your multiport board supports these ports, you
       should make use of them to avoid potential lockups if  the
       interrupt gets lost.

       In  order  to  set  these ports specify set_multiport as a
       parameter, and follow it with  the  multiport  parameters.
       The  multiport  parameters take the form of specifying the
       port that should be checked, a mask which  indicate  which
       bits in the register are significant, and finally, a match
       parameter which specifies what  the  significant  bits  in
       that  register  must  match  when there is no more pending
       work to be done.

       Up to four such port/mask/match combinations may be speci-
       fied.   The first such combinations should be specified by
       setting the parameters port1, mask1, and match1.  The sec-
       ond  such  combination  should  be  specified  with port2,
       mask2, and match2, and so on.  In order  to  disable  this
       multiport checking, set port1 to be zero.

       In  order  to view the current multiport settings, specify
       the parameter get_multiport on the command line.

       Here are some multiport settings for  some  common  serial
       boards:

              AST FourPort    port1 0x1BF match1 0xf mask1 0xf

              Boca BB-1004/8  port1 0x107 match1 0xff match1 0

              Boca BB-2016    port1 0x107 match1 0xff match1 0
                              port2 0x147 match2 0xff match2 0

Hayes ESP Configuration
       Setserial  may  also be used to configure ports on a Hayes
       ESP serial board.

       The following parameters when configuring ESP ports:

       rx_trigger
              This is the trigger level (in bytes) of the receive
              FIFO.  Larger values may result in fewer interrupts
              and hence better performance; however, a value  too
              high  could result in data loss. Valid values are 1
              through 1023.

       tx_trigger
              This is the trigger level (in bytes) of the  trans-
              mit  FIFO. Larger values may result in fewer inter-
              rupts and  hence  better  performance;  however,  a
              value  too  high  could result in degraded transmit
              performance. Valid values are 1 through 1023.

       flow_off
              This is the level (in bytes) at which the ESP  port
              will  "flow  off" the remote transmitter (i.e. tell
              him to stop stop sending more bytes).  Valid values
              are  1  through 1023.  This value should be greater
              than the receive trigger  level  and  the  flow  on
              level.

       flow_on
              This  is the level (in bytes) at which the ESP port
              will "flow on" the remote  transmitter  (i.e.  tell
              him to resume sending bytes) after having flowed it
              off.  Valid values are 1 through 1023.  This  value
              should be less than the flow off level, but greater
              than the receive trigger level.

       rx_timeout
              This is the amount of time that the ESP  port  will
              wait  after  receiving  the  final character before
              signaling an interrupt.  Valid values are 0 through
              255.  A value too high will increase latency, and a
              value too low will cause unnecessary interrupts.

CAUTION
       CAUTION: Configuring a serial port to use an incorrect I/O
       port can lock up your machine.

FILES
       /etc/rc.local /etc/rc.serial

SEE ALSO
       tty(4), ttys(4), kernel/chr_drv/serial.c

AUTHOR
       The  original  version  of  setserial  was written by Rick
       Sladkey (jrs@world.std.com), and was modified  by  Michael
       K. Johnson (johnsonm@stolaf.edu).

       This  version  has  since  been  rewritten from scratch by
       Theodore Ts'o (tytso@mit.edu)  on  1/1/93.   Any  bugs  or
       problems are solely his responsibility.

Setserial 2.15            November 1998                         1