MAN page from Old RedHat 5.X setserial-2.12-4.i386.rpm

SETSERIAL

Section: Linux Programmer's Manual (8)
Updated: 12 Feb 1995
Index

NAME

setserial - get/set Linux serial port information

SYNOPSIS

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

setserial -g[ -abv ]device1 ...

DESCRIPTION

setserialis a program designed to set and/or report the configuration informationassociated with a serial port. This information includes what I/Oport and IRQ a particular serial port is using, and whether or not thebreak key should be interpreted as the Secure Attention Key, and soon.

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 orderto initialize any additional serial ports, or to change the COM 1-4ports to a nonstadard configuration, thesetserial program should be used. Typically it is called from anrc.serialscript, which is usually run out of /etc/rc.local.

Thedeviceargument or arguments specifies the serial device which should be configured orinterrogated. It will usually have the following form:/dev/cua[0-3].

If no parameters are specified,setserialwill print out the port type (i.e., 8250, 16450, 16550, 16550A, 16650, 16750), the hardware I/O port, the hardware IRQ line, its "baud base," and some ofits operational flags.

If the-goption is given, the arguments to setserial are interpreted as a listof devices for which the characteristics of those devices should beprinted.

Without the -goption, the first argument to setserial is interpreted as the deviceto be modified or characteristics to be printed, and any additionalarguments are interpreted as parameters which should be assignedto that serial device.

For the most part, superuser privilege is required to set theconfiguration parameters of a serial port. A few serial port parameterscan be set by normal users, however, and these will be noted asexceptions in this manual page.

OPTIONS

Setserialaccepts the following options:

-a: When reporting the configuration of a serial device, print allavailable information.
-b: When reporting the configuration of a serial device, print a summaryof the device's configuration, which might be suitable for printingduring the bootup process, during the /etc/rc script.
-q: Be quiet. Setserialwill print fewer lines of output.
-v: Be verbose.Setserialwill 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

Theportoption sets the I/O port, as described above.

irq irq_number

Theirqoption sets the hardware IRQ, as described above.

uart uart_type

This option is used to set the UART type. The permitted types arenone,8250, 16450, 16550, 16550A, 16650, 16750. 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 typenonewill disable the port.

Some internal modems are billed as having a "16550A UART with a 1kbuffer". This is a lie. They do not have really have a 16550Acompatible UART; instead what they have is a 16450 compatible UARTwith a 1k receive buffer to prevent receiver overruns. This isimportant, because they do not have a transmit FIFO. Hence, they arenot compatible with a 16550A UART, and the autoconfiguration processwill correctly identify them as 16450's. If you attempt to overridethis using the uartparameter, you will see dropped characters during file transmissions.These UART's usually have other problems: theskip_testparameter also often must be specified.

autoconfigure

When this parameter is given, setserialwill ask the kernel to attempt to automatically configure the serialport. The I/O port must be correctly set; the kernel will attempt todetermine the UART type, and if theauto_irq parameter is set, Linux will attempt to automatically determine theIRQ. Theautoconfigureparameter should be given after theport,auto_irq, andskip_testparameters have been specified.

auto_irq

During autoconfiguration, try to determine the IRQ. This feature isnot guaranteed to always produce the correct result; some hardwareconfigurations will fool the Linux kernel. It is generally safer notto use the auto_irqfeature, but rather to specify the IRQ to be used explicitly, usingtheirq parameter.

^auto_irq

During autoconfiguration, donottry to determine the IRQ.

skip_test

During autoconfiguration, skip the UART test. Some internal modems donot have National Semiconductor compatible UART's, but have cheapimitations instead. Some of these cheasy imitations UART's do notfully support the loopback detection mode, which is used by the kernelto make sure there really is a UART at a particular address beforeattempting to configure it. So for certain internal modems you willneed to specify this parameter so Linux can initialize the UARTcorrectly.

^skip_test

During autoconfiguration, donotskip the UART test.

baud_base baud_base

This option sets the base baud rate, which is the clock frequency dividedby 16. Normally this value is 115200, which is also the fastest baudrate 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 requests38.4kb. In this case, the baud rate is thebaud_basedivided by thedivisor.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 thespd_custoption is selected and the serial port is set to 38.4kb by theapplication.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 shouldremain low on a serial line after the callout device is closed, beforethe blocked dialin device raises DTR again. The default value of thisoption is 50, or a half-second delay.

closing_wait delay

Specify the amount of time, in hundredths of a second, that the kernelshould wait for data to be transmitted from the serial port whileclosing the port, before the receiver has been disabled. If "none" isspecified, no delay will occur. If "infinite" is specified the kernel will wait indefinitely for the buffered data to be transmitted. The default setting of is "none".

closing_wait2 delay

Specify the amount of time, in hundredths of a second, that the kernelshould wait for data to be transmitted from the serial port whileclosing the port, after the receiver has been disabled. As with the closing_waitcommand, both "none" and "infinite" may be specified. The default settingis 3000, or 30 seconds of delay.

The default settings of closing_wait and closing_wait2 are generallyappropriate for most devices. If too long a delay is selected, thenthe serial port may hang for a long time if when a serial port whichis not connected, and has data pending, is closed. If too short adelay is selected, then there is a risk that some of the transmitteddata is output at all.

If the device is extremely slow, like a plotter, the values ofclosing_wait or closing_wait2 may need to be extended further.

If the device typically uses XON/XOFF handshaking, the default valuesof closing_wait and closing_wat2 should be reversed. This has adanger of not supressing "echo wars" between Linux and an echoingmodem, however.

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 witha different session ID to open that port until the first process hasclosed 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 adifferent process group to open that port until the first process hasclosed 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 hasfinished using a callout line (either by closing it or by the serialline being hung up) by returning EAGAIN to the open.

The application of this parameter is for getty's which are blocked ona serial port's dial in line. This allows the getty to reset themodem (which may have had its configuration modified by theapplication 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 thecallout device is hung up.

split_termios

Treat the termios settings used by the callout device and the termiossettings used by the dialin devices as separate.

^split_termios

Use the same termios structure to store both the dialin and calloutports. This is the default option.

callout_nohup

If this particular serial port is opened as a callout device, do nothangup the tty when carrier detect is dropped.

^callout_nohup

Do not skip hanging up the tty when a serial port is opened as acallout device. Of course, the HUPCL termios flag must be enabled ifthe hangup is to occur.

CONSIDERATIONS OF CONFIGURING SERIAL PORTS

It is important to note that setserial merely tells the Linux kernelwhere it should expect to find the I/O port and IRQ lines of aparticular serial port. It does *not* configure the hardware, theactual serial board, to use a particular I/O port. In order to dothat, you will need to physically program the serial board, usually bysetting some jumpers or by switching some DIP switches.

This section will provide some pointers in helping you decide how youwould 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 serialports. If you attempt to do this, one or both serial ports willbecome unreliable if you try to use both simultaneously. Thislimitation can be overcome by special multi-port serial port boards,which are designed to share multiple serial ports over a single IRQline. Multi-port serial cards supported by Linux include the ASTFourPort, the Accent Async board, the Usenet Serial II board, theBocaboard BB-1004, BB-1008, and BB-2016 boards, and the HUB-6 serialboard.

The selection of an alternative IRQ lineis difficult, since most of them are already used. The following tablelists the "standard MS-DOS" assignments of available IRQ lines:


IRQ 3: COM2IRQ 4: COM1IRQ 5: LPT2IRQ 7: LPT1

Most people find that IRQ 5 is a good choice, assuming that there isonly one parallel port active in the computer. Another good choice isIRQ 2 (aka IRQ 9); although this IRQ is sometimes used by networkcards, and very rarely VGA cards will be configured to use IRQ 2 as avertical retrace interrupt. If your VGA card is configured this way;try to disable it so you can reclaim that IRQ line for some othercard. It's not necessary for Linux and most other Operating systems.

The only other available IRQ lines are 3, 4, and 7, and these areprobably used by the other serial and parallel ports. (If your serialcard has a 16bit card edge connector, and supports higher interruptnumbers, 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 itin this manner.

IRQ's other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15, shouldnotbe used, since they are assigned to other hardware and cannot, in general,be changed. Here are the "standard" assignments:


IRQ  0      Timer channel 0IRQ  1      KeyboardIRQ  2      Cascade for controller 2IRQ  3      Serial port 2IRQ  4      Serial port 1IRQ  5      Parallel port 2 (Reserved in PS/2)IRQ  6      Floppy disketteIRQ  7      Parallel port 1IRQ  8      Real-time clockIRQ  9      Redirected to IRQ2IRQ 10      ReservedIRQ 11      ReservedIRQ 12      Reserved (Auxillary device in PS/2)IRQ 13      Math coprocessorIRQ 14      Hard disk controllerIRQ 15      Reserved

MULTIPORT CONFIGURATION

Certain multiport serial boards which share multiple ports on a singleIRQ use one or more ports to indicate whether or not there are anypending ports which need to be serviced. If your multiport boardsupports these ports, you should make use of them to avoid potentiallockups if the interrupt gets lost.

In order to set these ports specifyset_multiportas a parameter, and follow it with the multiport parameters. Themultiport parameters take the form of specifying the portthat should be checked, a maskwhich indicate which bits in the register are significant, and finally, amatchparameter 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. Thefirst such combinations should be specified by setting the parametersport1,mask1,andmatch1.The second such combination should be specified withport2,mask2,andmatch2,and so on. In order to disable this multiport checking, set port1to be zero.

In order to view the current multiport settings, specify the parameterget_multiporton the command line.

Here are some multiport settings for some common serial boards:


AST FourPort    port1 0x1BF match1 0xf mask1 0xfBoca BB-1004/8  port1 0x107 match1 0xff match1 0Boca BB-2016    port1 0x107 match1 0xff match1 0                 port2 0x147 match2 0xff match2 0

CAUTION

CAUTION: Using an invalid port can lock up your machine.

FILES

/etc/rc.local/etc/rc.serial

AUTHOR

The original version of setserial was written by Rick Sladkey(jrsAATTworld.std.com), and was modified by Michael K. Johnson(johnsonmAATTstolaf.edu).

This version has since been rewritten from scratch by Theodore Ts'o(tytsoAATTmit.edu) on 1/1/93. Any bugs or problems are solely hisresponsibility.

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
PARAMETERS
CONSIDERATIONS OF CONFIGURING SERIAL PORTS
MULTIPORT CONFIGURATION
CAUTION
FILES
SEE ALSO
AUTHOR

This document was created byman2html,using the manual pages.