17.2 Introduction

17.2.1 Terminology

bps: Bits per Second -- the rate at which data is transmitted
DTE: Data Terminal Equipment -- for example, your computer
DCE: Data Communications Equipment -- your modem
RS-232: EIA standard for hardware serial communications

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).

17.2.2 Cables and Ports

To connect a modem or terminal to your FreeBSD 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.

17.2.2.1 Cables

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.

17.2.2.1.1 Null-modem Cables

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.

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.

Signal	Pin #		Pin #	Signal
SG	7	connects to	7	SG
TxD	2	connects to	3	RxD
RxD	3	connects to	2	TxD
RTS	4	connects to	5	CTS
CTS	5	connects to	4	RTS
DTR	20	connects to	6	DSR
DCD	8		6	DSR
DSR	6	connects to	20	DTR

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.

17.2.2.1.2 Standard RS-232C Cables

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 FreeBSD system, and is also appropriate for some terminals.

17.2.2.2 Ports

Serial ports are the devices through which data is transferred between the FreeBSD host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in FreeBSD.

17.2.2.2.1 Kinds of Ports

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 FreeBSD system.

Most terminals will have DB25 ports. Personal computers, including PCs running FreeBSD, 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.

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.

17.2.2.2.2 Port Names

In FreeBSD, you access each serial port through an entry in the /dev directory. There are two different kinds of entries:

Call-in ports are named /dev/ttydN 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.
Call-out ports are named /dev/cuaaN. 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.

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.

17.2.3 Kernel Configuration

FreeBSD supports four serial ports by default. In the MS-DOS world, these are known as COM1, COM2, COM3, and COM4. FreeBSD 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.

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.

Tip: To view just the messages that have the word sio, use the command:
# /sbin/dmesg | grep 'sio'

For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:

sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550A
sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550A
sio3 at 0x2e8-0x2ef irq 9 on isa
sio3: type 16550A

If your kernel does not recognize all of your serial ports, you will probably need to configure a custom FreeBSD kernel for your system. For detailed information on configuring your kernel, please see Chapter 9.

The relevant device lines for your kernel configuration file would look like this, for FreeBSD 4.X:

device     sio0    at isa? port IO_COM1 irq 4
device      sio1    at isa? port IO_COM2 irq 3
device      sio2    at isa? port IO_COM3 irq 5
device      sio3    at isa? port IO_COM4 irq 9

and like this, for FreeBSD 5.X:

device     sio

You can comment-out or completely remove lines for devices you do not have in the case of FreeBSD 4.X; for FreeBSD 5.X you have to edit your /boot/device.hints file to configure your serial ports. Please refer to the sio(4) manual page for more information on serial ports and multiport boards configuration. Be careful if you are using a configuration file that was previously used for a different version of FreeBSD because the device flags and the syntax have changed between versions.

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).

17.2.4 Device Special Files

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/ttydN (dial-in) and /dev/cuaaN (call-out) devices. FreeBSD also provides initialization devices (/dev/ttyidN and /dev/cuaiaN) and locking devices (/dev/ttyldN and /dev/cualaN). 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), sio(4), and stty(1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.

17.2.4.1 Making Device Special Files

Note: FreeBSD 5.0 includes the devfs(5) filesystem which automatically creates device nodes as needed. If you are running a version of FreeBSD with devfs enabled then you can safely skip this section.

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.

MAKEDEV not only creates the /dev/ttydN device special files, but also the /dev/cuaaN, /dev/cuaiaN, /dev/cualaN, /dev/ttyldN, and /dev/ttyidN nodes.

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:

crw-rw----    1 uucp     dialer    28, 129 Feb 15 14:38 /dev/cuaa1
crw-rw----    1 uucp     dialer    28, 161 Feb 15 14:38 /dev/cuaia1
crw-rw----    1 uucp     dialer    28, 193 Feb 15 14:38 /dev/cuala1

These permissions allow the user uucp and users in the group dialer to use the call-out devices.

17.2.5 Serial Port Configuration

The ttydN (or cuaaN) 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

# stty -a -f /dev/ttyd1

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:

# stty -f /dev/ttyid5 clocal cs8 ixon ixoff

System-wide initialization of the serial devices is controlled in /etc/rc.serial. This file affects the default settings of serial devices.

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:

# stty -f /dev/ttyld5 57600

Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps.

Naturally, you should make the initial state and lock state devices writable only by the root account.