Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for setserial (redhat section 8)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 associ-
       ated 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 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 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 configuration 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  informa-
	      tion.

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

       -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 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 process will  cor-
	      rectly  identify	them  as 16450's.  If you attempt to override this using the uart
	      parameter, 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 automati-
	      cally 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 speci-
	      fied.

       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 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 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_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  clos-
	      ing_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 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  application 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 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 uti-
	      lization.  (Normally there is an average of 5-10ms latency  before  characters  are
	      handed  off  to  the line discpline to minimize overhead.)  This is off by default,
	      but certain 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 particular serial port.  It does *not* con-
       figure 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  con-
       figure 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 lim-
       itation 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 probably 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 supports these ports, you should make use of them to avoid poten-
       tial 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 specified.  The  first  such  combina-
       tions  should be specified by setting the parameters port1, mask1, and match1.  The second
       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 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 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 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 trans-
	      mitter (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  inter-
	      rupts.

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.17				   January 2000 			     SETSERIAL(8)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:55 PM.