(no commit message)
[ikiwiki.git] / docs / docs / newhandbook / serial_communications / index.mdwn
1 ## Chapter 18 Serial Communications 
2 [[!toc  levels=3]]
3
4 ## Synopsis 
5
6
7
8 UNIX® has always had support for serial communications. In fact, the very first UNIX machines relied on serial lines for user input and output. Things have changed a lot from the days when the average ***terminal*** consisted of a 10-character-per-second serial printer and a keyboard. This chapter will cover some of the ways in which DragonFly uses serial communications.
9
10
11
12 After reading this chapter, you will know:
13
14
15
16
17 * How to connect terminals to your DragonFly system.
18
19
20 * How to use a modem to dial out to remote hosts.
21
22
23 * How to allow remote users to login to your system with a modem.
24
25
26 * How to boot your system from a serial console.
27
28
29
30 Before reading this chapter, you should:
31
32
33
34
35 * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]).
36
37
38 * Understand UNIX permissions and processes ([basics.html Chapter 3]).
39
40
41 * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly.
42
43
44 ***
45
46
47 ## 18.1 Introduction 
48
49
50
51 ### 18.1.1 Terminology 
52
53
54
55 bps:: Bits per Second -- the rate at which data is transmitted;
56
57 DTE:: Data Terminal Equipment -- for example, your computer;
58
59 DCE:: Data Communications Equipment -- your modem;
60
61 RS-232:: EIA standard for hardware serial communications.
62
63
64
65 When talking about communications data rates, this section does not use the term ***baud***. Baud refers to the number of electrical state transitions that may be made in a period of time, while ***bps*** (bits per second) is the ***correct*** term to use (at least it does not seem to bother the curmudgeons quite as much).
66
67
68
69 ### 18.1.2 Cables and Ports 
70
71
72
73 To connect a modem or terminal to your DragonFly system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section.
74
75
76
77 #### 18.1.2.1 Cables 
78
79
80
81 There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard (***straight***) RS-232 cables. The documentation for your hardware should describe the type of cable required.
82
83
84
85 ##### 18.1.2.1.1 Null-modem Cables 
86
87
88
89 A null-modem cable passes some signals, such as ***signal ground***, straight through, but switches other signals. For example, the ***send data*** pin on one end goes to the ***receive data*** pin on the other end.
90
91
92
93 If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector.
94
95
96
97 [[!table  data="""
98 | Signal | Pin # |  | Pin # | Signal 
99  SG | 7 | connects to | 7 | SG 
100  TxD | 2 | connects to | 3 | RxD 
101  RxD | 3 | connects to | 2 | TxD 
102  RTS | 4 | connects to | 5 | CTS 
103  CTS | 5 | connects to | 4 | RTS 
104  DTR | 20 | connects to | 6 | DSR 
105  DCD | 8 |  | 6 | DSR 
106  DSR | 6 | connects to | 20 | DTR |
107
108 """]]
109
110  **Note:** Connect ***Data Set Ready*** (DSR) and ***Data Carrier Detect*** (DCD) internally in the connector hood, and then to ***Data Terminal Ready*** (DTR) in the remote hood.
111
112
113
114 ##### 18.1.2.1.2 Standard RS-232C Cables 
115
116
117
118 A standard serial cable passes all the RS-232C signals straight-through. That is, the ***send data*** pin on one end of the cable goes to the ***send data*** pin on the other end. This is the type of cable to use to connect a modem to your DragonFly system, and is also appropriate for some terminals.
119
120
121
122 #### 18.1.2.2 Ports 
123
124
125
126 Serial ports are the devices through which data is transferred between the DragonFly host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in DragonFly.
127
128
129
130 ##### 18.1.2.2.1 Kinds of Ports 
131
132
133
134 Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the DragonFly system.
135
136
137
138 Most terminals will have DB25 ports. Personal computers, including PCs running DragonFly, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports.
139
140
141
142 See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works too.
143
144
145
146 ##### 18.1.2.2.2 Port Names 
147
148
149
150 In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries:
151
152
153
154
155 * Call-in ports are named `/dev/ttyd`***N****** where `***N***` is the port number, starting from zero. Generally, you use the call-in port for terminals. Call-in ports require that the serial line assert the data carrier detect (DCD) signal to work correctly.
156
157
158 * Call-out ports are named `/dev/cuaa`***N******. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal.
159
160
161
162 If you have connected a terminal to the first serial port (`COM1` in MS-DOS®), then you will use `/dev/ttyd0` to refer to the terminal. If the terminal is on the second serial port (also known as `COM2`), use `/dev/ttyd1`, and so forth.
163
164
165
166 ### 18.1.3 Kernel Configuration 
167
168
169
170 DragonFly supports four serial ports by default. In the MS-DOS world, these are known as `COM1`, `COM2`, `COM3`, and `COM4`. DragonFly currently supports ***dumb*** multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports.
171
172
173
174 To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the `/sbin/dmesg` command to replay the kernel's boot messages. In particular, look for messages that start with the characters `sio`.
175
176
177
178  **Tip:** To view just the messages that have the word `sio`, use the command:
179
180
181
182     
183
184     # /sbin/dmesg | grep 'sio'
185
186
187
188
189
190 For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
191
192
193
194     
195
196     sio0 at 0x3f8-0x3ff irq 4 on isa
197
198     sio0: type 16550A
199
200     sio1 at 0x2f8-0x2ff irq 3 on isa
201
202     sio1: type 16550A
203
204     sio2 at 0x3e8-0x3ef irq 5 on isa
205
206     sio2: type 16550A
207
208     sio3 at 0x2e8-0x2ef irq 9 on isa
209
210     sio3: type 16550A
211
212
213
214
215
216 If your kernel does not recognize all of your serial ports, you will probably need to configure a custom DragonFly kernel for your system. For detailed information on configuring your kernel, please see [kernelconfig.html Chapter 10].
217
218
219
220 The relevant device lines for your kernel configuration file would look like this:
221
222
223
224     
225
226     device              sio0    at isa? port IO_COM1 irq 4
227
228     device              sio1    at isa? port IO_COM2 irq 3
229
230     device              sio2    at isa? port IO_COM3 irq 5
231
232     device              sio3    at isa? port IO_COM4 irq 9
233
234
235
236
237
238 You can comment-out or completely remove lines for devices you do not have. Please refer to the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio&section4) manual page for more information on serial ports and multiport boards configuration.
239
240
241
242  **Note:** `port IO_COM1` is a substitution for `port 0x3f8`, `IO_COM2` is `0x2f8`, `IO_COM3` is `0x3e8`, and `IO_COM4` is `0x2e8`, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports ***cannot*** share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines).
243
244
245
246 ### 18.1.4 Device Special Files 
247
248
249
250 Most devices in the kernel are accessed through ***device special files***, which are located in the `/dev` directory. The `sio` devices are accessed through the `/dev/ttyd`***N****** (dial-in) and `/dev/cuaa`***N****** (call-out) devices. DragonFly also provides initialization devices (`/dev/ttyid`***N****** and `/dev/cuaia`***N******) and locking devices (`/dev/ttyld`***N****** and `/dev/cuala`***N******). The initialization devices are used to initialize communications port parameters each time a port is opened, such as `crtscts` for modems which use `RTS/CTS` signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages [termios(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#termios&section4), [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sio&section=4), and [stty(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=stty&section=1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.
251
252
253
254 #### 18.1.4.1 Making Device Special Files 
255
256
257
258 A shell script called `MAKEDEV` in the `/dev` directory manages the device special files. To use `MAKEDEV` to make dial-up device special files for `COM1` (port 0), `cd` to `/dev` and issue the command `MAKEDEV ttyd0`. Likewise, to make dial-up device special files for `COM2` (port 1), use `MAKEDEV ttyd1`.
259
260
261
262 `MAKEDEV` not only creates the `/dev/ttyd`***N****** device special files, but also the `/dev/cuaa`***N******, `/dev/cuaia`***N******, `/dev/cuala`***N******, `/dev/ttyld`***N******, and `/dev/ttyid`***N****** nodes.
263
264
265
266 After making new device special files, be sure to check the permissions on the files (especially the `/dev/cua*` files) to make sure that only users who should have access to those device special files can read and write on them -- you probably do not want to allow your average user to use your modems to dial-out. The default permissions on the `/dev/cua*` files should be sufficient:
267
268
269
270     
271
272     crw-rw----    1 uucp     dialer    28, 129 Feb 15 14:38 /dev/cuaa1
273
274     crw-rw----    1 uucp     dialer    28, 161 Feb 15 14:38 /dev/cuaia1
275
276     crw-rw----    1 uucp     dialer    28, 193 Feb 15 14:38 /dev/cuala1
277
278
279
280
281
282 These permissions allow the user `uucp` and users in the group `dialer` to use the call-out devices.
283
284
285
286 ### 18.1.5 Serial Port Configuration 
287
288
289
290 The `ttyd`***N****** (or `cuaa`***N******) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command
291
292
293
294     
295
296     # stty -a -f /dev/ttyd1
297
298
299
300
301
302 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the ***initial state*** device. For example, to turn on `CLOCAL` mode, 8 bit communication, and `XON/XOFF` flow control by default for `ttyd5`, type:
303
304
305
306     
307
308     # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
309
310
311
312
313
314 System-wide initialization of the serial devices is controlled in `/etc/rc.serial`. This file affects the default settings of serial devices.
315
316
317
318 To prevent certain settings from being changed by an application, make adjustments to the ***lock state*** device. For example, to lock the speed of `ttyd5` to 57600 bps, type:
319
320
321
322     
323
324     # stty -f /dev/ttyld5 57600
325
326
327
328
329
330 Now, an application that opens `ttyd5` and tries to change the speed of the port will be stuck with 57600 bps.
331
332
333
334 Naturally, you should make the initial state and lock state devices writable only by the `root` account.
335
336
337
338 ***
339
340
341