sys-utils/setserial.8

.\" Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu)
.\" May be distributed under the GNU General Public License
.\" Portions of this text are from the README in setserial-2.01.tar.z,
.\" but I can't figure out who wrote that document.  If anyone knows,
.\" please tell me
.\"
.\" [tytso:19940519.2239EDT]  I did... - Ted Ts'o (tytso@mit.edu)
.\" Sat Aug 27 17:08:38 1994 Changes from Kai Petzke
.\" (wpp@marie.physik.tu-berlin.de) were applied by Rik Faith
.\" (faith@cs.unc.edu)
.\" "
.TH SETSERIAL 8 "27 August 1994" "Setserial 2.10" "Linux Programmer's Manual"
.SH NAME
setserial \- get/set Linux serial port information
.SH SYNOPSIS
.B setserial
.B "[ \-abqvVW ]"
device
.BR "[ " parameter1 " [ " arg " ] ] ..."

.B "setserial -g"
.B "[ \-abv ]"
device1 ...
.SH DESCRIPTION
.B 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
.B setserial 
program should be used.  Typically it is called from an
.I rc.serial
script, which is usually run out of 
.IR /etc/rc.local .

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

If no parameters are specified,
.B 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
.B \-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 
.B \-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.

.SH OPTIONS
.B Setserial
accepts the following options:

.TP
.B \-a
When reporting the configuration of a serial device, print all
available information.
.TP
.B \-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.
.TP
.B \-q
Be quiet.  
.B Setserial
will print fewer lines of output.
.TP
.B \-v
Be verbose.
.B Setserial
will print additional status output.
.TP
.B \-V
Display version and exit.
.TP
.B \-W
Do wild interrupt initialization and exit.

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

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

.TP
.BR port " port_number"
The
.B port
option sets the I/O port, as described above.
.TP
.BR irq " irq_number"
The
.B irq
option sets the hardware IRQ, as described above.
.TP
.BR uart " uart_type"
This option is used to set the UART type.  The permitted types are
.BR 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.
Setting the UART type to 8250, 16450, or 16550 will enable the serial
port without trying to use the FIFO. Using UART type
.B 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 overruns.  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 
.B uart
parameter, you will see dropped characters during file transmissions.
These UART's usually have other problems: the
.B skip_test
parameter also often must be specified.
.TP
.B autoconfig
When this parameter is given, 
.B 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
.B auto_irq 
parameter is set, Linux will attempt to automatically determine the
IRQ.  The
.B autoconfigure
parameter should be given after the
.BR port , auto_irq ", and" skip_test
parameters have been specified.
.TP
.B 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 
.B auto_irq
feature, but rather to specify the IRQ to be used explicitly, using
the
.B irq 
parameter.
.TP
.B ^auto_irq
During autoconfiguration, do
.I not
try to determine the IRQ.
.TP
.B 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.
.TP
.B ^skip_test
During autoconfiguration, do
.I not
skip the UART test.
.TP
.BR 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. 
.TP
.B
spd_hi
Use 57.6kb when the application requests 38.4kb.  
This parameter may be specified by a non-privileged user.
.TP
.B spd_vhi
Use 115kb when the application requests 38.4kb.
This parameter may be specified by a non-privileged user.
.TP
.B spd_cust
Use the custom divisor to set the speed when the application requests
38.4kb.  In this case, the baud rate is the
.B baud_base
divided by the
.BR divisor .
This parameter may be specified by a non-privileged user.
.TP
.B spd_normal
Use 38.4kb when the application requests 38.4kb.
This parameter may be specified by a non-privileged user.
.TP
.BR divisor " divisor"
This option sets the custom divison.  This divisor will be used then the
.B 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.
.TP
.B sak
Set the break key at the Secure Attention Key.
.TP
.B ^sak
disable the Secure Attention Key.
.TP
.B fourport
Configure the port as an AST Fourport card.
.TP
.B ^fourport
Disable AST Fourport configuration.
.TP
.BR 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.
.TP
.B 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.
.TP
.B ^session_lockout
Do not lock out callout port accesses across different sessions.
.TP
.B 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.
.TP
.B ^pgrp_lockout
Do not lock out callout port accesses across different process groups.
.TP
.B 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.
.TP
.B ^hup_notify
Do not notify a process blocked on opening a dial in line when the
callout device is hung up.
.TP
.B split_termios
Treat the termios settings used by the callout device and the termios
settings used by the dialin devices as separate.  
.TP
.B ^split_termios
Use the same termios structure to store both the dialin and callout
ports.  This is the default option.
.TP
.B callout_nohup
If this particular serial port is opened as a callout device, do not
hangup the tty when carrier detect is dropped.
.TP
.B ^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.
.SH 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:

.nf
.RS
/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
.RE
.fi

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:

.nf
.RS
IRQ 3: COM2
IRQ 4: COM1
IRQ 5: LPT2
IRQ 7: LPT1
.RE
.fi

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
.I not
be used, since they are assigned to other hardware and cannot, in general,
be changed.  Here are the "standard" assignments:

.nf
.RS
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
.RE
.fi


.SH CAUTION
CAUTION: Using an invalid port can lock up your machine.
.SH FILES
.BR /etc/rc.local
.BR /etc/rc.serial
.SH "SEE ALSO"
.BR tty (4),
.BR ttys (4),
kernel/chr_drv/serial.c
.SH 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.