27.2 Introduction

Warning: As of FreeBSD 8.0, device nodes for serial ports have been renamed from /dev/cuadN to /dev/cuauN and from /dev/ttydN to /dev/ttyuN. FreeBSD 7.X users will have to adapt the following documentation according to these changes.

27.2.1 Terminology


Bits per Second (bps) is the rate at which data is transmitted.


An example of a Data Terminal Equipment (DTE) is a computer.


An example of a Data Communications Equipment (DTE) is a modem.


The original standard for hardware serial communications. It is now usually referred to as TIA-232

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 is the correct term to use.

27.2.2 Cables and Ports

To connect a modem or serial terminal to a FreeBSD system, a serial port on the computer and the proper cable to connect to the serial device are needed. Users who are already familiar with serial hardware and cabling can safely skip this section. Cables

There are several different kinds of serial cables. The two most common types are null-modem cables and standard RS-232 cables. The documentation for the hardware should describe the type of cable required. Null-modem Cables

A null-modem cable passes some signals, such as “Signal Ground”, straight through, but switches other signals. For example, the “Transmitted Data” pin on one end goes to the “Received Data” pin on the other end.

A null-modem cable can be constructed for use with terminals. The following table shows the RS-232C signal names and the pin numbers on a DB-25 connector. While the standard calls for a straight-through pin 1 to pin 1 Protective Ground line, it is often omitted. Some terminals work using only pins 2, 3, and 7, while others require different configurations than the examples shown below.

Table 27-1. DB-25 to DB-25 Null-Modem Cable

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

The next two tables show two other common schemes.

Table 27-2. DB-9 to DB-9 Null-Modem Cable

Signal Pin #   Pin # Signal
RD 2 connects to 3 TD
TD 3 connects to 2 RD
DTR 4 connects to 6 DSR
DTR 4 connects to 1 DCD
SG 5 connects to 5 SG
DSR 6 connects to 4 DTR
DCD 1 connects to 4 DTR
RTS 7 connects to 8 CTS
CTS 8 connects to 7 RTS

Table 27-3. DB-9 to DB-25 Null-Modem Cable

Signal Pin #   Pin # Signal
RD 2 connects to 2 TD
TD 3 connects to 3 RD
DTR 4 connects to 6 DSR
DTR 4 connects to 8 DCD
SG 5 connects to 7 SG
DSR 6 connects to 20 DTR
DCD 1 connects to 20 DTR
RTS 7 connects to 5 CTS
CTS 8 connects to 4 RTS

Note: When one pin at one end connects to a pair of pins at the other end, it is usually implemented with one short wire between the pair of pins in their connector and a long wire to the other single pin.

The above designs seem to be the most popular. In another variation, SG connects to SG, TD connects to RD, RTS and CTS connect to DCD, DTR connects to DSR, and vice-versa. Standard RS-232C Cables

A standard serial cable passes all of the RS-232C signals straight through. The “Transmitted Data” pin on one end of the cable goes to the “Transmitted Data” pin on the other end. This is the type of cable used to connect a modem to the FreeBSD system, and is also appropriate for some terminals. 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. Kinds of Ports

Several kinds of serial ports exist. Before purchasing or constructing a cable, make sure it will fit the ports on the terminal and on the FreeBSD system.

Most terminals have DB-25 ports. Personal computers may have DB-25 or DB-9 ports. A multiport serial card may have RJ-12 or RJ-45 ports.

See the documentation that accompanied the hardware for specifications on the kind of port or visually verify the type of port. Port Names

In FreeBSD, each serial port is accessed through an entry in /dev. There are two different kinds of entries:

  • Call-in ports are named /dev/ttyuN where N is the port number, starting from zero. Generally, the call-in port is used 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/cuauN. Call-out ports are usually not used for terminals, but are used for modems. The call-out port can be used if the serial cable or the terminal does not support the carrier detect signal.

If a terminal is connected to the first serial port(COM1), use /dev/ttyu0 to refer to the terminal. If the terminal is on the second serial port (COM2), use /dev/ttyu1, and so forth.

27.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 the kernel recognizes the serial ports, watch for messages while the kernel is booting, or use /sbin/dmesg to replay the kernel's boot messages. Look for messages that start with the characters uart for FreeBSD 8.0 or higher, or sio for FreeBSD 7.4 or older.

Tip: To view just the messages that have the word uart or sio depending on the installed version of FreeBSD, use the commands:

# /sbin/dmesg | grep 'uart'
# /sbin/dmesg | grep 'sio'

For example, on a FreeBSD 7.X 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 the kernel does not recognize all of the serial ports, configure /boot/device.hints. When editing this file, one can comment out or completely remove lines for devices that do not exist on the system.

Refer to sio(4) for more information on configuring serial ports and multiport boards. When using a configuration file that was previously used for a different version of FreeBSD be aware that the device flags and the syntax may 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. These are fairly common port addresses for their respective serial ports and interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. 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.

27.2.4 Device Special Files

Most devices in the kernel are accessed through “device special files” which are located in /dev class="directory". The sio devices are accessed through the /dev/ttyuN (dial-in) and /dev/cuauN (call-out) devices. FreeBSD also provides initialization devices (/dev/ttyuN.init and /dev/cuauN.init) and locking devices (/dev/ttyuN.lock and /dev/cuauN.lock). 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. Refer to termios(4), sio(4), and stty(1) for information on terminal settings, locking and initializing devices, and setting terminal options, respectively.

27.2.5 Serial Port Configuration

The ttyuN (or cuauN) is the regular device to open for applications. When a process opens the device, it will have a default set of terminal I/O settings. These settings can be viewed with the command:

# stty -a -f /dev/ttyu1

When the settings are changed for a device, the settings are in effect until the device is closed. When the device is reopened, it goes back to the default set. To permanently change the default set, 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 for ttyu5, type:

# stty -f /dev/ttyu5.init clocal cs8 ixon ixoff

System-wide initialization of serial devices is controlled by /etc/rc.d/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 ttyu5 to 57600 bps, type:

# stty -f /dev/ttyu5.lock 57600

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

The initial state and lock state devices should only be writable by root.