setserial

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       setserial - get/set Linux serial port information


SYNOPSIS

       setserial [ -abqvVW ] device [ parameter1 [ arg ] ] ...

       setserial -g [ -abv ] 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), 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.

       -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.



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,  and
              16550A.  Since the 8250 and 16450 UARTS do not have
              FIFO's, and since  the  original  16550  have  bugs
              which  make the FIFO's unusable, the FIFO will only
              be used on chips identifiied as 16550A UARTs.  Set-
              ting  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 autoconfigure 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.

       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.


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




CAUTION

       CAUTION: Using an invalid 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.
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.