1 .\" Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu)
2 .\" May be distributed under the GNU General Public License
3 .\" Portions of this text are from the README in setserial-2.01.tar.z,
4 .\" but I can't figure out who wrote that document. If anyone knows,
7 .\" [tytso:19940519.2239EDT] I did... - Ted Ts'o (tytso@mit.edu)
9 .TH SETSERIAL 8 "January 2000" "Setserial 2.17
11 setserial \- get/set Linux serial port information
16 .BR "[ " parameter1 " [ " arg " ] ] ..."
23 is a program designed to set and/or report the configuration information
24 associated with a serial port. This information includes what I/O
25 port and IRQ a particular serial port is using, and whether or not the
26 break key should be interpreted as the Secure Attention Key, and so
29 During the normal bootup process, only COM ports 1-4 are initialized,
30 using the default I/O ports and IRQ values, as listed below. In order
31 to initialize any additional serial ports, or to change the COM 1-4
32 ports to a nonstadard configuration, the
34 program should be used. Typically it is called from an
36 script, which is usually run out of
41 argument or arguments specifies the serial device which should be configured or
42 interrogated. It will usually have the following form:
45 If no parameters are specified,
47 will print out the port type (i.e., 8250, 16450, 16550, 16550A, etc.), the
48 hardware I/O port, the hardware IRQ line, its "baud base," and some of
49 its operational flags.
53 option is given, the arguments to setserial are interpreted as a list
54 of devices for which the characteristics of those devices should be
59 option, the first argument to setserial is interpreted as the device
60 to be modified or characteristics to be printed, and any additional
61 arguments are interpreted as parameters which should be assigned
62 to that serial device.
64 For the most part, superuser privilege is required to set the
65 configuration parameters of a serial port. A few serial port parameters
66 can be set by normal users, however, and these will be noted as
67 exceptions in this manual page.
71 accepts the following options:
75 When reporting the configuration of a serial device, print all
76 available information.
79 When reporting the configuration of a serial device, print a summary
80 of the device's configuration, which might be suitable for printing
81 during the bootup process, during the /etc/rc script.
84 Print out the configuration information of the serial port in a form which
85 can be fed back to setserial as command-line arguments.
90 will print fewer lines of output.
95 will print additional status output.
98 Display version and exit.
101 Do wild interrupt initialization and exit. This option is no longer
102 relevant in Linux kernels after version 2.1.
105 Zero out the serial flags before starting to set flags. This is related
106 to the automatic saving of serial flags using the \-G flag.
109 The following parameters can be assigned to a serial port.
111 All argument values are assumed to be in decimal unless preceeded by "0x".
114 .BR port " port_number"
117 option sets the I/O port, as described above.
119 .BR irq " irq_number"
122 option sets the hardware IRQ, as described above.
124 .BR uart " uart_type"
125 This option is used to set the UART type. The permitted types are
127 8250, 16450, 16550, 16550A, 16650, 16650V2, 16654, 16750, 16850, 16950, and
131 will disable the port.
133 Some internal modems are billed as having a "16550A UART with a 1k
134 buffer". This is a lie. They do not have really have a 16550A
135 compatible UART; instead what they have is a 16450 compatible UART
136 with a 1k receive buffer to prevent receiver overruns. This is
137 important, because they do not have a transmit FIFO. Hence, they are
138 not compatible with a 16550A UART, and the autoconfiguration process
139 will correctly identify them as 16450's. If you attempt to override
142 parameter, you will see dropped characters during file transmissions.
143 These UART's usually have other problems: the
145 parameter also often must be specified.
148 When this parameter is given,
150 will ask the kernel to attempt to automatically configure the serial
151 port. The I/O port must be correctly set; the kernel will attempt to
152 determine the UART type, and if the
154 parameter is set, Linux will attempt to automatically determine the
157 parameter should be given after the
158 .BR port , auto_irq ", and " skip_test
159 parameters have been specified.
162 During autoconfiguration, try to determine the IRQ. This feature is
163 not guaranteed to always produce the correct result; some hardware
164 configurations will fool the Linux kernel. It is generally safer not
167 feature, but rather to specify the IRQ to be used explicitly, using
173 During autoconfiguration, do
175 try to determine the IRQ.
178 During autoconfiguration, skip the UART test. Some internal modems do
179 not have National Semiconductor compatible UART's, but have cheap
180 imitations instead. Some of these cheasy imitations UART's do not
181 fully support the loopback detection mode, which is used by the kernel
182 to make sure there really is a UART at a particular address before
183 attempting to configure it. So for certain internal modems you will
184 need to specify this parameter so Linux can initialize the UART
188 During autoconfiguration, do
192 .BR baud_base " baud_base"
193 This option sets the base baud rate, which is the clock frequency divided
194 by 16. Normally this value is 115200, which is also the fastest baud
195 rate which the UART can support.
199 Use 57.6kb when the application requests 38.4kb.
200 This parameter may be specified by a non-privileged user.
203 Use 115kb when the application requests 38.4kb.
204 This parameter may be specified by a non-privileged user.
207 Use 230kb when the application requests 38.4kb.
208 This parameter may be specified by a non-privileged user.
211 Use 460kb when the application requests 38.4kb.
212 This parameter may be specified by a non-privileged user.
215 Use the custom divisor to set the speed when the application requests
216 38.4kb. In this case, the baud rate is the
220 This parameter may be specified by a non-privileged user.
223 Use 38.4kb when the application requests 38.4kb.
224 This parameter may be specified by a non-privileged user.
226 .BR divisor " divisor"
227 This option sets the custom divison. This divisor will be used then the
229 option is selected and the serial port is set to 38.4kb by the
231 This parameter may be specified by a non-privileged user.
234 Set the break key at the Secure Attention Key.
237 disable the Secure Attention Key.
240 Configure the port as an AST Fourport card.
243 Disable AST Fourport configuration.
245 .BR close_delay " delay"
246 Specify the amount of time, in hundredths of a second, that DTR should
247 remain low on a serial line after the callout device is closed, before
248 the blocked dialin device raises DTR again. The default value of this
249 option is 50, or a half-second delay.
251 .BR closing_wait " delay"
252 Specify the amount of time, in hundredths of a second, that the kernel
253 should wait for data to be transmitted from the serial port while
254 closing the port. If "none" is
255 specified, no delay will occur. If "infinite" is specified the kernel
256 will wait indefinitely for the buffered data to be transmitted.
257 The default setting is 3000 or 30 seconds of delay.
258 This default is generally appropriate for most devices. If too long
259 a delay is selected, then
260 the serial port may hang for a long time if when a serial port which
261 is not connected, and has data pending, is closed. If too short a
262 delay is selected, then there is a risk that some of the transmitted
263 data is output at all. If the device is extremely slow, like a plotter,
264 the closing_wait may need to be larger.
267 Lock out callout port (/dev/cuaXX) accesses across different sessions.
268 That is, once a process has opened a port, do not allow a process with
269 a different session ID to open that port until the first process has
273 Do not lock out callout port accesses across different sessions.
276 Lock out callout port (/dev/cuaXX) accesses across different process groups.
277 That is, once a process has opened a port, do not allow a process in a
278 different process group to open that port until the first process has
282 Do not lock out callout port accesses across different process groups.
285 Notify a process blocked on opening a dial in line when a process has
286 finished using a callout line (either by closing it or by the serial
287 line being hung up) by returning EAGAIN to the open.
289 The application of this parameter is for getty's which are blocked on
290 a serial port's dial in line. This allows the getty to reset the
291 modem (which may have had its configuration modified by the
292 application using the callout device) before blocking on the open again.
295 Do not notify a process blocked on opening a dial in line when the
296 callout device is hung up.
299 Treat the termios settings used by the callout device and the termios
300 settings used by the dialin devices as separate.
303 Use the same termios structure to store both the dialin and callout
304 ports. This is the default option.
307 If this particular serial port is opened as a callout device, do not
308 hangup the tty when carrier detect is dropped.
311 Do not skip hanging up the tty when a serial port is opened as a
312 callout device. Of course, the HUPCL termios flag must be enabled if
313 the hangup is to occur.
316 Minimize the receive latency of the serial device at the cost of
317 greater CPU utilization. (Normally there is an average of 5-10ms
318 latency before characters are handed off to the line discpline to
319 minimize overhead.) This is off by default, but certain real-time
320 applications may find this useful.
323 Optimize for efficient CPU processing of serial characters at the cost of
324 paying an average of 5-10ms of latency before the characters are processed.
326 .SH CONSIDERATIONS OF CONFIGURING SERIAL PORTS
327 It is important to note that setserial merely tells the Linux kernel
328 where it should expect to find the I/O port and IRQ lines of a
329 particular serial port. It does *not* configure the hardware, the
330 actual serial board, to use a particular I/O port. In order to do
331 that, you will need to physically program the serial board, usually by
332 setting some jumpers or by switching some DIP switches.
334 This section will provide some pointers in helping you decide how you
335 would like to configure your serial ports.
337 The "standard MS-DOS" port associations are given below:
341 /dev/ttys0 (COM1), port 0x3f8, irq 4
342 /dev/ttys1 (COM2), port 0x2f8, irq 3
343 /dev/ttys2 (COM3), port 0x3e8, irq 4
344 /dev/ttys3 (COM4), port 0x2e8, irq 3
348 Due to the limitations in the design of the AT/ISA bus architecture,
349 normally an IRQ line may not be shared between two or more serial
350 ports. If you attempt to do this, one or both serial ports will
351 become unreliable if you try to use both simultaneously. This
352 limitation can be overcome by special multi-port serial port boards,
353 which are designed to share multiple serial ports over a single IRQ
354 line. Multi-port serial cards supported by Linux include the AST
355 FourPort, the Accent Async board, the Usenet Serial II board, the
356 Bocaboard BB-1004, BB-1008, and BB-2016 boards, and the HUB-6 serial
359 The selection of an alternative IRQ line
360 is difficult, since most of them are already used. The following table
361 lists the "standard MS-DOS" assignments of available IRQ lines:
372 Most people find that IRQ 5 is a good choice, assuming that there is
373 only one parallel port active in the computer. Another good choice is
374 IRQ 2 (aka IRQ 9); although this IRQ is sometimes used by network
375 cards, and very rarely VGA cards will be configured to use IRQ 2 as a
376 vertical retrace interrupt. If your VGA card is configured this way;
377 try to disable it so you can reclaim that IRQ line for some other
378 card. It's not necessary for Linux and most other Operating systems.
380 The only other available IRQ lines are 3, 4, and 7, and these are
381 probably used by the other serial and parallel ports. (If your serial
382 card has a 16bit card edge connector, and supports higher interrupt
383 numbers, then IRQ 10, 11, 12, and 15 are also available.)
385 On AT class machines, IRQ 2 is seen as IRQ 9, and Linux will interpret it
388 IRQ's other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15, should
390 be used, since they are assigned to other hardware and cannot, in general,
391 be changed. Here are the "standard" assignments:
395 IRQ 0 Timer channel 0
397 IRQ 2 Cascade for controller 2
400 IRQ 5 Parallel port 2 (Reserved in PS/2)
401 IRQ 6 Floppy diskette
402 IRQ 7 Parallel port 1
403 IRQ 8 Real-time clock
404 IRQ 9 Redirected to IRQ2
407 IRQ 12 Reserved (Auxillary device in PS/2)
408 IRQ 13 Math coprocessor
409 IRQ 14 Hard disk controller
414 .SH MULTIPORT CONFIGURATION
416 Certain multiport serial boards which share multiple ports on a single
417 IRQ use one or more ports to indicate whether or not there are any
418 pending ports which need to be serviced. If your multiport board
419 supports these ports, you should make use of them to avoid potential
420 lockups if the interrupt gets lost.
422 In order to set these ports specify
424 as a parameter, and follow it with the multiport parameters. The
425 multiport parameters take the form of specifying the
427 that should be checked, a
429 which indicate which bits in the register are significant, and finally, a
431 parameter which specifies what the significant bits in that register must
432 match when there is no more pending work to be done.
434 Up to four such port/mask/match combinations may be specified. The
435 first such combinations should be specified by setting the parameters
440 The second such combination should be specified with
445 and so on. In order to disable this multiport checking, set
449 In order to view the current multiport settings, specify the parameter
453 Here are some multiport settings for some common serial boards:
457 AST FourPort port1 0x1BF mask1 0xf match1 0xf
459 Boca BB-1004/8 port1 0x107 mask1 0xff match1 0
461 Boca BB-2016 port1 0x107 mask1 0xff match1 0
462 port2 0x147 mask2 0xff match2 0
466 .SH Hayes ESP Configuration
468 may also be used to configure ports on a Hayes ESP serial board.
470 The following parameters when configuring ESP ports:
473 This is the trigger level (in bytes) of the receive FIFO. Larger
474 values may result in fewer interrupts and hence better performance;
475 however, a value too high could result in data loss. Valid values
479 This is the trigger level (in bytes) of the transmit FIFO. Larger
480 values may result in fewer interrupts and hence better performance;
481 however, a value too high could result in degraded transmit
482 performance. Valid values are 1 through 1023.
485 This is the level (in bytes) at which the ESP port will "flow off"
486 the remote transmitter (i.e. tell him to stop stop sending more
487 bytes). Valid values are 1 through 1023. This value should be
488 greater than the receive trigger level and the flow on level.
491 This is the level (in bytes) at which the ESP port will "flow on"
492 the remote transmitter (i.e. tell him to resume sending bytes) after
493 having flowed it off. Valid values are 1 through 1023. This value
494 should be less than the flow off level, but greater than the receive
498 This is the amount of time that the ESP port will wait after
499 receiving the final character before signaling an interrupt. Valid
500 values are 0 through 255. A value too high will increase latency,
501 and a value too low will cause unnecessary interrupts.
504 CAUTION: Configuring a serial port to use an incorrect I/O port
505 can lock up your machine.
512 kernel/chr_drv/serial.c
514 The original version of setserial was written by Rick Sladkey
515 (jrs@world.std.com), and was modified by Michael K. Johnson
516 (johnsonm@stolaf.edu).
518 This version has since been rewritten from scratch by Theodore Ts'o
519 (tytso@mit.edu) on 1/1/93. Any bugs or problems are solely his