diff options
Diffstat (limited to 'sys-utils/setserial.8')
| -rw-r--r-- | sys-utils/setserial.8 | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/sys-utils/setserial.8 b/sys-utils/setserial.8 new file mode 100644 index 000000000..539db21a2 --- /dev/null +++ b/sys-utils/setserial.8 @@ -0,0 +1,392 @@ +.\" 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. |