setserial



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 particular 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 nonstadard configuration, the setserial  program  should  be
       used.   Typically  it is called from an rc.serial script, which is usu-
       ally 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 follow-
       ing 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  characteristics  of  those  devices
       should be printed.

       Without  the  -g option, the first argument to setserial is interpreted
       as the device to be modified or characteristics 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  configu-
       ration  parameters  of a serial port.  A few serial port parameters can
       be set by normal users, however, 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 configuration, 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 setserial  as  command-line  argu-
              ments.

       -q     Be quiet.  Setserial will print fewer lines of output.

       -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 permitted types
              are none, 8250, 16450, 16550,  16550A,  16650,  16650V2,  16654,
              16750,  16850, 16950, and 16954.  Using UART type none will dis-
              able 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  com-
              patible  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 process 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 parame-
              ter 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, and skip_test
              parameters have been specified.

       auto_irq
              During autoconfiguration, try to determine the IRQ.   This  fea-
              ture  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  internal 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  fre-
              quency  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_shi
              Use 230kb when the application requests 38.4kb.  This  parameter
              may be specified by a non-privileged user.

       spd_warp
              Use  460kb 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 application.  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 second, 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-second delay.

       closing_wait delay
              Specify the amount of time, in hundredths of a second, that  the
              kernel  should  wait  for data to be transmitted from the serial
              port while closing the port.  If "none" is specified,  no  delay
              will  occur.  If  "infinite"  is  specified the kernel will wait
              indefinitely  for the buffered  data  to  be  transmitted.   The
              default setting is 3000 or 30 seconds of delay.  This default is
              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 closing_wait may
              need to be larger.

       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 different session ID to  open  that  port
              until the first process has closed it.

       ^session_lockout
              Do not lock out callout port accesses across different 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 different process group  to  open  that
              port until the first process has closed it.

       ^pgrp_lockout
              Do  not  lock out callout port accesses across different process
              groups.

       hup_notify
              Notify a process blocked on opening a dial in line when  a  pro-
              cess  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 modi-
              fied by the application using the callout device) before  block-
              ing 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 callout 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 characters are handed off to the line dis-
              cpline to minimize overhead.)  This is off by default, but  cer-
              tain real-time applications may find this useful.

       ^low_latency
              Optimize  for  efficient  CPU processing of serial characters at
              the cost of paying an average of 5-10ms of  latency  before  the
              characters are processed.  This is the default.


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 particu-
       lar  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 computer.  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
       vertical  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 prob-
       ably used by the other serial and parallel ports.  (If your serial card
       has a 16bit card edge connector, 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 hardware 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 serviced.  If your multiport board sup-
       ports these ports, you should make use of them to avoid potential lock-
       ups 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 reg-
       ister must match when there is no more pending work to be done.

       Up to four such port/mask/match combinations  may  be  specified.   The
       first  such  combinations should be specified by setting the parameters
       port1, mask1, and match1.  The second such combination should be speci-
       fied  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 mask1 0xf match1 0xf

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

              Boca BB-2016    port1 0x107 mask1 0xff match1 0
                              port2 0x147 mask2 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 perfor-
              mance; 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 transmit FIFO.
              Larger values may result in fewer interrupts  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  (john-
       sonm@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 respon-
       sibility.



Setserial 2.17                   January 2000                     SETSERIAL(8)

Man(1) output converted with man2html