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)
