]>
Commit | Line | Data |
---|---|---|
6dbe3af9 KZ |
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, | |
5 | .\" please tell me | |
6 | .\" | |
7 | .\" [tytso:19940519.2239EDT] I did... - Ted Ts'o (tytso@mit.edu) | |
8 | .\" Sat Aug 27 17:08:38 1994 Changes from Kai Petzke | |
9 | .\" (wpp@marie.physik.tu-berlin.de) were applied by Rik Faith | |
10 | .\" (faith@cs.unc.edu) | |
11 | .\" " | |
12 | .TH SETSERIAL 8 "27 August 1994" "Setserial 2.10" "Linux Programmer's Manual" | |
13 | .SH NAME | |
14 | setserial \- get/set Linux serial port information | |
15 | .SH SYNOPSIS | |
16 | .B setserial | |
17 | .B "[ \-abqvVW ]" | |
18 | device | |
19 | .BR "[ " parameter1 " [ " arg " ] ] ..." | |
20 | ||
21 | .B "setserial -g" | |
22 | .B "[ \-abv ]" | |
23 | device1 ... | |
24 | .SH DESCRIPTION | |
25 | .B setserial | |
26 | is a program designed to set and/or report the configuration information | |
27 | associated with a serial port. This information includes what I/O | |
28 | port and IRQ a particular serial port is using, and whether or not the | |
29 | break key should be interpreted as the Secure Attention Key, and so | |
30 | on. | |
31 | ||
32 | During the normal bootup process, only COM ports 1-4 are initialized, | |
33 | using the default I/O ports and IRQ values, as listed below. In order | |
34 | to initialize any additional serial ports, or to change the COM 1-4 | |
35 | ports to a nonstadard configuration, the | |
36 | .B setserial | |
37 | program should be used. Typically it is called from an | |
38 | .I rc.serial | |
39 | script, which is usually run out of | |
40 | .IR /etc/rc.local . | |
41 | ||
42 | The | |
43 | .I device | |
44 | argument or arguments specifies the serial device which should be configured or | |
45 | interrogated. It will usually have the following form: | |
46 | .BR /dev/cua[0-3] . | |
47 | ||
48 | If no parameters are specified, | |
49 | .B setserial | |
50 | will print out the port type (i.e., 8250, 16450, 16550, 16550A), the | |
51 | hardware I/O port, the hardware IRQ line, its "baud base," and some of | |
52 | its operational flags. | |
53 | ||
54 | If the | |
55 | .B \-g | |
56 | option is given, the arguments to setserial are interpreted as a list | |
57 | of devices for which the characteristics of those devices should be | |
58 | printed. | |
59 | ||
60 | Without the | |
61 | .B \-g | |
62 | option, the first argument to setserial is interpreted as the device | |
63 | to be modified or characteristics to be printed, and any additional | |
64 | arguments are interpreted as parameters which should be assigned | |
65 | to that serial device. | |
66 | ||
67 | For the most part, superuser privilege is required to set the | |
68 | configuration parameters of a serial port. A few serial port parameters | |
69 | can be set by normal users, however, and these will be noted as | |
70 | exceptions in this manual page. | |
71 | ||
72 | .SH OPTIONS | |
73 | .B Setserial | |
74 | accepts the following options: | |
75 | ||
76 | .TP | |
77 | .B \-a | |
78 | When reporting the configuration of a serial device, print all | |
79 | available information. | |
80 | .TP | |
81 | .B \-b | |
82 | When reporting the configuration of a serial device, print a summary | |
83 | of the device's configuration, which might be suitable for printing | |
84 | during the bootup process, during the /etc/rc script. | |
85 | .TP | |
86 | .B \-q | |
87 | Be quiet. | |
88 | .B Setserial | |
89 | will print fewer lines of output. | |
90 | .TP | |
91 | .B \-v | |
92 | Be verbose. | |
93 | .B Setserial | |
94 | will print additional status output. | |
95 | .TP | |
96 | .B \-V | |
97 | Display version and exit. | |
98 | .TP | |
99 | .B \-W | |
100 | Do wild interrupt initialization and exit. | |
101 | ||
102 | .SH PARAMETERS | |
103 | The following parameters can be assigned to a serial port. | |
104 | ||
105 | All argument values are assumed to be in decimal unless preceeded by "0x". | |
106 | ||
107 | .TP | |
108 | .BR port " port_number" | |
109 | The | |
110 | .B port | |
111 | option sets the I/O port, as described above. | |
112 | .TP | |
113 | .BR irq " irq_number" | |
114 | The | |
115 | .B irq | |
116 | option sets the hardware IRQ, as described above. | |
117 | .TP | |
118 | .BR uart " uart_type" | |
119 | This option is used to set the UART type. The permitted types are | |
120 | .BR none , | |
121 | 8250, 16450, 16550, and 16550A. Since the 8250 and 16450 UARTS do not have | |
122 | FIFO's, and since the original 16550 have bugs which make the FIFO's unusable, | |
123 | the FIFO will only be used on chips identifiied as 16550A UARTs. | |
124 | Setting the UART type to 8250, 16450, or 16550 will enable the serial | |
125 | port without trying to use the FIFO. Using UART type | |
126 | .B none | |
127 | will disable the port. | |
128 | ||
129 | Some internal modems are billed as having a "16550A UART with a 1k | |
130 | buffer". This is a lie. They do not have really have a 16550A | |
131 | compatible UART; instead what they have is a 16450 compatible UART | |
132 | with a 1k receive buffer to prevent receiver overruns. This is | |
133 | important, because they do not have a transmit FIFO. Hence, they are | |
134 | not compatible with a 16550A UART, and the autoconfiguration process | |
135 | will correctly identify them as 16450's. If you attempt to override | |
136 | this using the | |
137 | .B uart | |
138 | parameter, you will see dropped characters during file transmissions. | |
139 | These UART's usually have other problems: the | |
140 | .B skip_test | |
141 | parameter also often must be specified. | |
142 | .TP | |
143 | .B autoconfig | |
144 | When this parameter is given, | |
145 | .B setserial | |
146 | will ask the kernel to attempt to automatically configure the serial | |
147 | port. The I/O port must be correctly set; the kernel will attempt to | |
148 | determine the UART type, and if the | |
149 | .B auto_irq | |
150 | parameter is set, Linux will attempt to automatically determine the | |
151 | IRQ. The | |
152 | .B autoconfigure | |
153 | parameter should be given after the | |
154 | .BR port , auto_irq ", and" skip_test | |
155 | parameters have been specified. | |
156 | .TP | |
157 | .B auto_irq | |
158 | During autoconfiguration, try to determine the IRQ. This feature is | |
159 | not guaranteed to always produce the correct result; some hardware | |
160 | configurations will fool the Linux kernel. It is generally safer not | |
161 | to use the | |
162 | .B auto_irq | |
163 | feature, but rather to specify the IRQ to be used explicitly, using | |
164 | the | |
165 | .B irq | |
166 | parameter. | |
167 | .TP | |
168 | .B ^auto_irq | |
169 | During autoconfiguration, do | |
170 | .I not | |
171 | try to determine the IRQ. | |
172 | .TP | |
173 | .B skip_test | |
174 | During autoconfiguration, skip the UART test. Some internal modems do | |
175 | not have National Semiconductor compatible UART's, but have cheap | |
176 | imitations instead. Some of these cheasy imitations UART's do not | |
177 | fully support the loopback detection mode, which is used by the kernel | |
178 | to make sure there really is a UART at a particular address before | |
179 | attempting to configure it. So for certain internal modems you will | |
180 | need to specify this parameter so Linux can initialize the UART | |
181 | correctly. | |
182 | .TP | |
183 | .B ^skip_test | |
184 | During autoconfiguration, do | |
185 | .I not | |
186 | skip the UART test. | |
187 | .TP | |
188 | .BR baud_base " baud_base" | |
189 | This option sets the base baud rate, which is the clock frequency divided | |
190 | by 16. Normally this value is 115200, which is also the fastest baud | |
191 | rate which the UART can support. | |
192 | .TP | |
193 | .B | |
194 | spd_hi | |
195 | Use 57.6kb when the application requests 38.4kb. | |
196 | This parameter may be specified by a non-privileged user. | |
197 | .TP | |
198 | .B spd_vhi | |
199 | Use 115kb when the application requests 38.4kb. | |
200 | This parameter may be specified by a non-privileged user. | |
201 | .TP | |
202 | .B spd_cust | |
203 | Use the custom divisor to set the speed when the application requests | |
204 | 38.4kb. In this case, the baud rate is the | |
205 | .B baud_base | |
206 | divided by the | |
207 | .BR divisor . | |
208 | This parameter may be specified by a non-privileged user. | |
209 | .TP | |
210 | .B spd_normal | |
211 | Use 38.4kb when the application requests 38.4kb. | |
212 | This parameter may be specified by a non-privileged user. | |
213 | .TP | |
214 | .BR divisor " divisor" | |
215 | This option sets the custom divison. This divisor will be used then the | |
216 | .B spd_cust | |
217 | option is selected and the serial port is set to 38.4kb by the | |
218 | application. | |
219 | This parameter may be specified by a non-privileged user. | |
220 | .TP | |
221 | .B sak | |
222 | Set the break key at the Secure Attention Key. | |
223 | .TP | |
224 | .B ^sak | |
225 | disable the Secure Attention Key. | |
226 | .TP | |
227 | .B fourport | |
228 | Configure the port as an AST Fourport card. | |
229 | .TP | |
230 | .B ^fourport | |
231 | Disable AST Fourport configuration. | |
232 | .TP | |
233 | .BR close_delay " delay" | |
234 | Specify the amount of time, in hundredths of a second, that DTR should | |
235 | remain low on a serial line after the callout device is closed, before | |
236 | the blocked dialin device raises DTR again. The default value of this | |
237 | option is 50, or a half-second delay. | |
238 | .TP | |
239 | .B session_lockout | |
240 | Lock out callout port (/dev/cuaXX) accesses across different sessions. | |
241 | That is, once a process has opened a port, do not allow a process with | |
242 | a different session ID to open that port until the first process has | |
243 | closed it. | |
244 | .TP | |
245 | .B ^session_lockout | |
246 | Do not lock out callout port accesses across different sessions. | |
247 | .TP | |
248 | .B pgrp_lockout | |
249 | Lock out callout port (/dev/cuaXX) accesses across different process groups. | |
250 | That is, once a process has opened a port, do not allow a process in a | |
251 | different process group to open that port until the first process has | |
252 | closed it. | |
253 | .TP | |
254 | .B ^pgrp_lockout | |
255 | Do not lock out callout port accesses across different process groups. | |
256 | .TP | |
257 | .B hup_notify | |
258 | Notify a process blocked on opening a dial in line when a process has | |
259 | finished using a callout line (either by closing it or by the serial | |
260 | line being hung up) by returning EAGAIN to the open. | |
261 | ||
262 | The application of this parameter is for getty's which are blocked on | |
263 | a serial port's dial in line. This allows the getty to reset the | |
264 | modem (which may have had its configuration modified by the | |
265 | application using the callout device) before blocking on the open again. | |
266 | .TP | |
267 | .B ^hup_notify | |
268 | Do not notify a process blocked on opening a dial in line when the | |
269 | callout device is hung up. | |
270 | .TP | |
271 | .B split_termios | |
272 | Treat the termios settings used by the callout device and the termios | |
273 | settings used by the dialin devices as separate. | |
274 | .TP | |
275 | .B ^split_termios | |
276 | Use the same termios structure to store both the dialin and callout | |
277 | ports. This is the default option. | |
278 | .TP | |
279 | .B callout_nohup | |
280 | If this particular serial port is opened as a callout device, do not | |
281 | hangup the tty when carrier detect is dropped. | |
282 | .TP | |
283 | .B ^callout_nohup | |
284 | Do not skip hanging up the tty when a serial port is opened as a | |
285 | callout device. Of course, the HUPCL termios flag must be enabled if | |
286 | the hangup is to occur. | |
287 | .SH CONSIDERATIONS OF CONFIGURING SERIAL PORTS | |
288 | It is important to note that setserial merely tells the Linux kernel | |
289 | where it should expect to find the I/O port and IRQ lines of a | |
290 | particular serial port. It does *not* configure the hardware, the | |
291 | actual serial board, to use a particular I/O port. In order to do | |
292 | that, you will need to physically program the serial board, usually by | |
293 | setting some jumpers or by switching some DIP switches. | |
294 | ||
295 | This section will provide some pointers in helping you decide how you | |
296 | would like to configure your serial ports. | |
297 | ||
298 | The "standard MS-DOS" port associations are given below: | |
299 | ||
300 | .nf | |
301 | .RS | |
302 | /dev/ttyS0 (COM1), port 0x3f8, irq 4 | |
303 | /dev/ttyS1 (COM2), port 0x2f8, irq 3 | |
304 | /dev/ttyS2 (COM3), port 0x3e8, irq 4 | |
305 | /dev/ttyS3 (COM4), port 0x2e8, irq 3 | |
306 | .RE | |
307 | .fi | |
308 | ||
309 | Due to the limitations in the design of the AT/ISA bus architecture, | |
310 | normally an IRQ line may not be shared between two or more serial | |
311 | ports. If you attempt to do this, one or both serial ports will | |
312 | become unreliable if you try to use both simultaneously. This | |
313 | limitation can be overcome by special multi-port serial port boards, | |
314 | which are designed to share multiple serial ports over a single IRQ | |
315 | line. Multi-port serial cards supported by Linux include the AST | |
316 | FourPort, the Accent Async board, the Usenet Serial II board, the | |
317 | Bocaboard BB-1004, BB-1008, and BB-2016 boards, and the HUB-6 serial | |
318 | board. | |
319 | ||
320 | The selection of an alternative IRQ line | |
321 | is difficult, since most of them are already used. The following table | |
322 | lists the "standard MS-DOS" assignments of available IRQ lines: | |
323 | ||
324 | .nf | |
325 | .RS | |
326 | IRQ 3: COM2 | |
327 | IRQ 4: COM1 | |
328 | IRQ 5: LPT2 | |
329 | IRQ 7: LPT1 | |
330 | .RE | |
331 | .fi | |
332 | ||
333 | Most people find that IRQ 5 is a good choice, assuming that there is | |
334 | only one parallel port active in the computer. Another good choice is | |
335 | IRQ 2 (aka IRQ 9); although this IRQ is sometimes used by network | |
336 | cards, and very rarely VGA cards will be configured to use IRQ 2 as a | |
337 | vertical retrace interrupt. If your VGA card is configured this way; | |
338 | try to disable it so you can reclaim that IRQ line for some other | |
339 | card. It's not necessary for Linux and most other Operating systems. | |
340 | ||
341 | The only other available IRQ lines are 3, 4, and 7, and these are | |
342 | probably used by the other serial and parallel ports. (If your serial | |
343 | card has a 16bit card edge connector, and supports higher interrupt | |
344 | numbers, then IRQ 10, 11, 12, and 15 are also available.) | |
345 | ||
346 | On AT class machines, IRQ 2 is seen as IRQ 9, and Linux will interpret it | |
347 | in this manner. | |
348 | ||
349 | IRQ's other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15, should | |
350 | .I not | |
351 | be used, since they are assigned to other hardware and cannot, in general, | |
352 | be changed. Here are the "standard" assignments: | |
353 | ||
354 | .nf | |
355 | .RS | |
356 | IRQ 0 Timer channel 0 | |
357 | IRQ 1 Keyboard | |
358 | IRQ 2 Cascade for controller 2 | |
359 | IRQ 3 Serial port 2 | |
360 | IRQ 4 Serial port 1 | |
361 | IRQ 5 Parallel port 2 (Reserved in PS/2) | |
362 | IRQ 6 Floppy diskette | |
363 | IRQ 7 Parallel port 1 | |
364 | IRQ 8 Real-time clock | |
365 | IRQ 9 Redirected to IRQ2 | |
366 | IRQ 10 Reserved | |
367 | IRQ 11 Reserved | |
368 | IRQ 12 Reserved (Auxillary device in PS/2) | |
369 | IRQ 13 Math coprocessor | |
370 | IRQ 14 Hard disk controller | |
371 | IRQ 15 Reserved | |
372 | .RE | |
373 | .fi | |
374 | ||
375 | ||
376 | .SH CAUTION | |
377 | CAUTION: Using an invalid port can lock up your machine. | |
378 | .SH FILES | |
379 | .BR /etc/rc.local | |
380 | .BR /etc/rc.serial | |
381 | .SH "SEE ALSO" | |
382 | .BR tty (4), | |
383 | .BR ttys (4), | |
384 | kernel/chr_drv/serial.c | |
385 | .SH AUTHOR | |
386 | The original version of setserial was written by Rick Sladkey | |
387 | (jrs@world.std.com), and was modified by Michael K. Johnson | |
388 | (johnsonm@stolaf.edu). | |
389 | ||
390 | This version has since been rewritten from scratch by Theodore Ts'o | |
391 | (tytso@mit.edu) on 1/1/93. Any bugs or problems are solely his | |
392 | responsibility. |