1SETSERIAL(8) System Manager's Manual SETSERIAL(8)
2
6 setserial - get/set Linux serial port information
7
9 setserial [ -abqvVWz ] device [ parameter1 [ arg ] ] ...
10 setserial -g [ -abGv ] device1 ...
12
14 setserial is a program designed to set and/or report the configuration
15 information associated with a serial port. This information includes
16 what I/O port and IRQ a particular serial port is using, and whether or
17 not the break key should be interpreted as the Secure Attention Key,
18 and so on.
19 During the normal bootup process, only COM ports 1-4 are initialized,
21 using the default I/O ports and IRQ values, as listed below. In order
22 to initialize any additional serial ports, or to change the COM 1-4
23 ports to a nonstadard configuration, the setserial program should be
24 used. Typically it is called from an rc.serial script, which is usu‐
25 ally run out of /etc/rc.local.
26 The device argument or arguments specifies the serial device which
28 should be configured or interrogated. It will usually have the follow‐
29 ing form: /dev/cua[0-3].
30 If no parameters are specified, setserial will print out the port type
32 (i.e., 8250, 16450, 16550, 16550A, etc.), the hardware I/O port, the
33 hardware IRQ line, its "baud base," and some of its operational flags.
34 If the -g option is given, the arguments to setserial are interpreted
36 as a list of devices for which the characteristics of those devices
37 should be printed.
38 Without the -g option, the first argument to setserial is interpreted
40 as the device to be modified or characteristics to be printed, and any
41 additional arguments are interpreted as parameters which should be
42 assigned to that serial device.
43 For the most part, superuser privilege is required to set the configu‐
45 ration parameters of a serial port. A few serial port parameters can
46 be set by normal users, however, and these will be noted as exceptions
47 in this manual page.
48
51 Setserial accepts the following options:
52 -a When reporting the configuration of a serial device, print all
55 available information.
56 -b When reporting the configuration of a serial device, print a
58 summary of the device's configuration, which might be suitable
59 for printing during the bootup process, during the /etc/rc
60 script.
61 -G Print out the configuration information of the serial port in a
63 form which can be fed back to setserial as command-line argu‐
64 ments.
65 -q Be quiet. Setserial will print fewer lines of output.
67 -v Be verbose. Setserial will print additional status output.
69 -V Display version and exit.
71 -W Do wild interrupt initialization and exit. This option is no
73 longer relevant in Linux kernels after version 2.1.
74 -z Zero out the serial flags before starting to set flags. This is
76 related to the automatic saving of serial flags using the -G
77 flag.
78
81 The following parameters can be assigned to a serial port.
82 All argument values are assumed to be in decimal unless preceeded by
84 "0x".
85 port port_number
88 The port option sets the I/O port, as described above.
89 irq irq_number
91 The irq option sets the hardware IRQ, as described above.
92 uart uart_type
94 This option is used to set the UART type. The permitted types
95 are none, 8250, 16450, 16550, 16550A, 16650, 16650V2, 16654,
96 16750, 16850, 16950, and 16954. Using UART type none will dis‐
97 able the port.
98 Some internal modems are billed as having a "16550A UART with a
100 1k buffer". This is a lie. They do not have really have a
101 16550A compatible UART; instead what they have is a 16450 com‐
102 patible UART with a 1k receive buffer to prevent receiver over‐
103 runs. This is important, because they do not have a transmit
104 FIFO. Hence, they are not compatible with a 16550A UART, and
105 the autoconfiguration process will correctly identify them as
106 16450's. If you attempt to override this using the uart parame‐
107 ter, you will see dropped characters during file transmissions.
108 These UART's usually have other problems: the skip_test parame‐
109 ter also often must be specified.
110 autoconfig
112 When this parameter is given, setserial will ask the kernel to
113 attempt to automatically configure the serial port. The I/O
114 port must be correctly set; the kernel will attempt to determine
115 the UART type, and if the auto_irq parameter is set, Linux will
116 attempt to automatically determine the IRQ. The autoconfig
117 parameter should be given after the port,auto_irq, and skip_test
118 parameters have been specified.
119 auto_irq
121 During autoconfiguration, try to determine the IRQ. This fea‐
122 ture is not guaranteed to always produce the correct result;
123 some hardware configurations will fool the Linux kernel. It is
124 generally safer not to use the auto_irq feature, but rather to
125 specify the IRQ to be used explicitly, using the irq parameter.
126 ^auto_irq
128 During autoconfiguration, do not try to determine the IRQ.
129 skip_test
131 During autoconfiguration, skip the UART test. Some internal
132 modems do not have National Semiconductor compatible UART's, but
133 have cheap imitations instead. Some of these cheasy imitations
134 UART's do not fully support the loopback detection mode, which
135 is used by the kernel to make sure there really is a UART at a
136 particular address before attempting to configure it. So for
137 certain internal modems you will need to specify this parameter
138 so Linux can initialize the UART correctly.
139 ^skip_test
141 During autoconfiguration, do not skip the UART test.
142 baud_base baud_base
144 This option sets the base baud rate, which is the clock fre‐
145 quency divided by 16. Normally this value is 115200, which is
146 also the fastest baud rate which the UART can support.
147 spd_hi Use 57.6kb when the application requests 38.4kb. This parameter
149 may be specified by a non-privileged user.
150 spd_vhi
152 Use 115kb when the application requests 38.4kb. This parameter
153 may be specified by a non-privileged user.
154 spd_shi
156 Use 230kb when the application requests 38.4kb. This parameter
157 may be specified by a non-privileged user.
158 spd_warp
160 Use 460kb when the application requests 38.4kb. This parameter
161 may be specified by a non-privileged user.
162 spd_cust
164 Use the custom divisor to set the speed when the application
165 requests 38.4kb. In this case, the baud rate is the baud_base
166 divided by the divisor. This parameter may be specified by a
167 non-privileged user.
168 spd_normal
170 Use 38.4kb when the application requests 38.4kb. This parameter
171 may be specified by a non-privileged user.
172 divisor divisor
174 This option sets the custom divison. This divisor will be used
175 then the spd_cust option is selected and the serial port is set
176 to 38.4kb by the application. This parameter may be specified
177 by a non-privileged user.
178 sak Set the break key at the Secure Attention Key.
180 ^sak disable the Secure Attention Key.
182 fourport
184 Configure the port as an AST Fourport card.
185 ^fourport
187 Disable AST Fourport configuration.
188 close_delay delay
190 Specify the amount of time, in hundredths of a second, that DTR
191 should remain low on a serial line after the callout device is
192 closed, before the blocked dialin device raises DTR again. The
193 default value of this option is 50, or a half-second delay.
194 closing_wait delay
196 Specify the amount of time, in hundredths of a second, that the
197 kernel should wait for data to be transmitted from the serial
198 port while closing the port. If "none" is specified, no delay
199 will occur. If "infinite" is specified the kernel will wait
200 indefinitely for the buffered data to be transmitted. The
201 default setting is 3000 or 30 seconds of delay. This default is
202 generally appropriate for most devices. If too long a delay is
203 selected, then the serial port may hang for a long time if when
204 a serial port which is not connected, and has data pending, is
205 closed. If too short a delay is selected, then there is a risk
206 that some of the transmitted data is output at all. If the
207 device is extremely slow, like a plotter, the closing_wait may
208 need to be larger.
209 session_lockout
211 Lock out callout port (/dev/cuaXX) accesses across different
212 sessions. That is, once a process has opened a port, do not
213 allow a process with a different session ID to open that port
214 until the first process has closed it.
215 ^session_lockout
217 Do not lock out callout port accesses across different sessions.
218 pgrp_lockout
220 Lock out callout port (/dev/cuaXX) accesses across different
221 process groups. That is, once a process has opened a port, do
222 not allow a process in a different process group to open that
223 port until the first process has closed it.
224 ^pgrp_lockout
226 Do not lock out callout port accesses across different process
227 groups.
228 hup_notify
230 Notify a process blocked on opening a dial in line when a
231 process has finished using a callout line (either by closing it
232 or by the serial line being hung up) by returning EAGAIN to the
233 open.
234 The application of this parameter is for getty's which are
236 blocked on a serial port's dial in line. This allows the getty
237 to reset the modem (which may have had its configuration modi‐
238 fied by the application using the callout device) before block‐
239 ing on the open again.
240 ^hup_notify
242 Do not notify a process blocked on opening a dial in line when
243 the callout device is hung up.
244 split_termios
246 Treat the termios settings used by the callout device and the
247 termios settings used by the dialin devices as separate.
248 ^split_termios
250 Use the same termios structure to store both the dialin and
251 callout ports. This is the default option.
252 callout_nohup
254 If this particular serial port is opened as a callout device, do
255 not hangup the tty when carrier detect is dropped.
256 ^callout_nohup
258 Do not skip hanging up the tty when a serial port is opened as a
259 callout device. Of course, the HUPCL termios flag must be
260 enabled if the hangup is to occur.
261 low_latency
263 Minimize the receive latency of the serial device at the cost of
264 greater CPU utilization. (Normally there is an average of
265 5-10ms latency before characters are handed off to the line dis‐
266 cpline to minimize overhead.) This is off by default, but cer‐
267 tain real-time applications may find this useful.
268 ^low_latency
270 Optimize for efficient CPU processing of serial characters at
271 the cost of paying an average of 5-10ms of latency before the
272 characters are processed. This is the default.
273
275 It is important to note that setserial merely tells the Linux kernel
276 where it should expect to find the I/O port and IRQ lines of a particu‐
277 lar serial port. It does *not* configure the hardware, the actual
278 serial board, to use a particular I/O port. In order to do that, you
279 will need to physically program the serial board, usually by setting
280 some jumpers or by switching some DIP switches.
281 This section will provide some pointers in helping you decide how you
283 would like to configure your serial ports.
284 The "standard MS-DOS" port associations are given below:
286 /dev/ttys0 (COM1), port 0x3f8, irq 4
288 /dev/ttys1 (COM2), port 0x2f8, irq 3
289 /dev/ttys2 (COM3), port 0x3e8, irq 4
290 /dev/ttys3 (COM4), port 0x2e8, irq 3
291 Due to the limitations in the design of the AT/ISA bus architecture,
293 normally an IRQ line may not be shared between two or more serial
294 ports. If you attempt to do this, one or both serial ports will become
295 unreliable if you try to use both simultaneously. This limitation can
296 be overcome by special multi-port serial port boards, which are
297 designed to share multiple serial ports over a single IRQ line. Multi-
298 port serial cards supported by Linux include the AST FourPort, the
299 Accent Async board, the Usenet Serial II board, the Bocaboard BB-1004,
300 BB-1008, and BB-2016 boards, and the HUB-6 serial board.
301 The selection of an alternative IRQ line is difficult, since most of
303 them are already used. The following table lists the "standard MS-DOS"
304 assignments of available IRQ lines:
305 IRQ 3: COM2
307 IRQ 4: COM1
308 IRQ 5: LPT2
309 IRQ 7: LPT1
310 Most people find that IRQ 5 is a good choice, assuming that there is
312 only one parallel port active in the computer. Another good choice is
313 IRQ 2 (aka IRQ 9); although this IRQ is sometimes used by network
314 cards, and very rarely VGA cards will be configured to use IRQ 2 as a
315 vertical retrace interrupt. If your VGA card is configured this way;
316 try to disable it so you can reclaim that IRQ line for some other card.
317 It's not necessary for Linux and most other Operating systems.
318 The only other available IRQ lines are 3, 4, and 7, and these are prob‐
320 ably used by the other serial and parallel ports. (If your serial card
321 has a 16bit card edge connector, and supports higher interrupt numbers,
322 then IRQ 10, 11, 12, and 15 are also available.)
323 On AT class machines, IRQ 2 is seen as IRQ 9, and Linux will interpret
325 it in this manner.
326 IRQ's other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15, should not be
328 used, since they are assigned to other hardware and cannot, in general,
329 be changed. Here are the "standard" assignments:
330 IRQ 0 Timer channel 0
332 IRQ 1 Keyboard
333 IRQ 2 Cascade for controller 2
334 IRQ 3 Serial port 2
335 IRQ 4 Serial port 1
336 IRQ 5 Parallel port 2 (Reserved in PS/2)
337 IRQ 6 Floppy diskette
338 IRQ 7 Parallel port 1
339 IRQ 8 Real-time clock
340 IRQ 9 Redirected to IRQ2
341 IRQ 10 Reserved
342 IRQ 11 Reserved
343 IRQ 12 Reserved (Auxillary device in PS/2)
344 IRQ 13 Math coprocessor
345 IRQ 14 Hard disk controller
346 IRQ 15 Reserved
347
350 Certain multiport serial boards which share multiple ports on a single
351 IRQ use one or more ports to indicate whether or not there are any
352 pending ports which need to be serviced. If your multiport board sup‐
353 ports these ports, you should make use of them to avoid potential lock‐
354 ups if the interrupt gets lost.
355 In order to set these ports specify set_multiport as a parameter, and
357 follow it with the multiport parameters. The multiport parameters take
358 the form of specifying the port that should be checked, a mask which
359 indicate which bits in the register are significant, and finally, a
360 match parameter which specifies what the significant bits in that reg‐
361 ister must match when there is no more pending work to be done.
362 Up to four such port/mask/match combinations may be specified. The
364 first such combinations should be specified by setting the parameters
365 port1, mask1, and match1. The second such combination should be speci‐
366 fied with port2, mask2, and match2, and so on. In order to disable
367 this multiport checking, set port1 to be zero.
368 In order to view the current multiport settings, specify the parameter
370 get_multiport on the command line.
371 Here are some multiport settings for some common serial boards:
373 AST FourPort port1 0x1BF mask1 0xf match1 0xf
375 Boca BB-1004/8 port1 0x107 mask1 0xff match1 0
377 Boca BB-2016 port1 0x107 mask1 0xff match1 0
379 port2 0x147 mask2 0xff match2 0
380
383 Setserial may also be used to configure ports on a Hayes ESP serial
384 board.
385 The following parameters when configuring ESP ports:
387 rx_trigger
389 This is the trigger level (in bytes) of the receive FIFO. Larger
390 values may result in fewer interrupts and hence better perfor‐
391 mance; however, a value too high could result in data loss.
392 Valid values are 1 through 1023.
393 tx_trigger
395 This is the trigger level (in bytes) of the transmit FIFO.
396 Larger values may result in fewer interrupts and hence better
397 performance; however, a value too high could result in degraded
398 transmit performance. Valid values are 1 through 1023.
399 flow_off
401 This is the level (in bytes) at which the ESP port will "flow
402 off" the remote transmitter (i.e. tell him to stop stop sending
403 more bytes). Valid values are 1 through 1023. This value
404 should be greater than the receive trigger level and the flow on
405 level.
406 flow_on
408 This is the level (in bytes) at which the ESP port will "flow
409 on" the remote transmitter (i.e. tell him to resume sending
410 bytes) after having flowed it off. Valid values are 1 through
411 1023. This value should be less than the flow off level, but
412 greater than the receive trigger level.
413 rx_timeout
415 This is the amount of time that the ESP port will wait after
416 receiving the final character before signaling an interrupt.
417 Valid values are 0 through 255. A value too high will increase
418 latency, and a value too low will cause unnecessary interrupts.
419
422 CAUTION: Configuring a serial port to use an incorrect I/O port can
423 lock up your machine.
424
426 /etc/rc.local /etc/rc.serial
427
429 tty(4), ttys(4), kernel/chr_drv/serial.c
430
432 The original version of setserial was written by Rick Sladkey
433 (jrs@world.std.com), and was modified by Michael K. Johnson (john‐
434 sonm@stolaf.edu).
435 This version has since been rewritten from scratch by Theodore Ts'o
437 (tytso@mit.edu) on 1/1/93. Any bugs or problems are solely his respon‐
438 sibility.
439Setserial 2.17 January 2000 SETSERIAL(8)