COM(4)

📦
version 11.0 · 2 versions
, in nixpkgs unstable

💖 com(4) — the serial communications interface for RS-232C, bestie edition 💖

Okay so like, this is the com driver, and it's giving "your computer wants to talk to the outside world over a serial cable" energy. We're talking RS-232C realness. Let me walk you through it, no cap.

✨ SYNOPSIS ✨

Here's the whole vibe of how you attach these things. There's a LOT of hardware that plays nice with com, so buckle up:

com0 at isa? port "IO_COM1" irq 4
com1 at isa? port "IO_COM2" irq 3
com* at acpi?
com* at cardbus?
com* at isapnp?
com* at mca? slot ?
com* at mhzc?
com* at ofisa?
com* at pcmcia?
com* at pcmcom?
com* at pnpbios? index ?
com* at puc? port ?
com* at xirc?
options COM_HAYESP
options PPS_SYNC
options PPS_TRAILING_EDGE
options RND_COM

And then there's the platform-specific stuff, because of course every architecture has opinions:

🎀 Amiga 🎀

com* at clockport?

🦋 Arm32 🦋

com0 at mainbus? base 0x00210fe0
com1 at mainbus? base 0x00210be0
com0 at pxaip?

🌸 HP 9000/300 and 400 Series 🌸

com* at dio? scode ?
com* at frodo? offset ?

💅 HP 9000/700 and 800 Series 💅

com* at dino?
com* at gsc?
com* at ssio?

🫶 IBM PowerPC 4xx 🫶

com* at opb?

😭 SPARC 😭

com* at ebus?
com* at obio0

🔥 x68k 🔥

com0 at intio0 addr 0xefff00 intr 240
com1 at intio0 addr 0xefff10 intr 241

💜 DESCRIPTION 💜

So the com driver is the wingman for NS8250-, NS16450-, and NS16550-based EIA RS-232C (that's CCITT V.28, iykyk) communications interfaces. Basically serial ports, bestie.

Quick tea on the chips:

  • The NS8250 and NS16450 have single character buffers — lowkey tiny.
  • The NS16550 has a 16 character buffer — she ate, honestly. 🔥

Input and output for each line can be set to one of these baud rates, and yes I'm listing every single one because we don't skip details here:

50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, or 115200

…or literally any other baud rate that's a factor of 115200. Slay, math. ✨

The ttyXX devices are the traditional dial-in devices. The dtyXX devices are for dial-out. (Peep tty(4) for more on that.)

options COM_HAYESP adds support for the Hayes ESP serial board. Iconic.

options PPS_SYNC enables code to use the Data Carrier Detect (DCD) signal line to attach to an external precision clock source (think GPS, CDMA) that generates a Pulse Per Second (PPS) signal. This is what ntpd(8) uses to discipline the system clock and more accurately count/measure time. See options(4) for way more discussion on that.

With options RND_COM enabled, the com driver can be used to collect entropy for the rnd(4) entropy pool. The entropy is generated from interrupt randomness. Vibes. 🦋

🌈 Arm32 specific 🌈

If flags 1 is specified, the com driver will not set the MCR_IENABLE bit on the UART. This is mainly for use on AST multiport boards, where the MCR_IENABLE bit is used to control whether or not the devices use a shared interrupt. Main character energy on those boards fr.

🍓 FILES 🍓

These are the device files you'll be hanging out with:

  • /dev/dty00
  • /dev/dty01
  • /dev/dty02
  • /dev/tty00
  • /dev/tty01
  • /dev/tty02

🚨 DIAGNOSTICS 🚨

com%d: %d silo overflows — The input "silo" has overflowed and incoming data has been lost. 😭 Not the data loss…

com%d: weird interrupt: iir=%x — The device has generated an unexpected interrupt, with the code listed right there. Weird flex but ok. 💀

👑 SEE ALSO 👑

Go off, related man pages: acpi(4), ast(4), cardbus(4), i386/pnpbios(4), isa(4), isapnp(4), mca(4), mhzc(4), ofisa(4), options(4), pcmcia(4), pcmcom(4), puc(4), pxaip(4), rtfps(4), tty(4), xirc(4), ntpd(8)

⭐ HISTORY ⭐

Fun fact: the com driver was originally derived from the HP9000/300 dca driver. Glow-up of the century honestly.

🙈 BUGS 🙈

Data loss is possible on busy systems with unbuffered UARTs at high speed. This is the danger zone, bestie — keep it in mind.

Also: the name of this driver and the constants which define the locations of the various serial ports are holdovers from DOS. We don't talk about that era. 💅

Okay that's the whole page, you're officially a com driver expert now, go forth and slay your serial connections 🫶✨💖

This iconic little manual page is brought to you by Debian, dated March 4, 2017. 🎀

📦 where this page comes from