INTRO(4)

💖 INTRO(4) — the whole vibe of section 4 💖

okay bestie, welcome to intro — the lil intro to devices and device drivers. this is the section 4 of the Kernel Interfaces Manual and it's literally your gateway drug to how FreeBSD talks to hardware. grab a boba, we're going in 🧋✨

---

✨ NAME ✨

intro — introduction to devices and device drivers 🦋

---

🌸 DESCRIPTION 🌸

so this whole section is the tea on devices, device drivers, and miscellaneous hardware. that's the assignment. that's the whole section. 💅

👑 The device abstraction

"Device" is basically the word we use for hardware-ish stuff that belongs to the system — think disks, printers, or a graphics display with its keyboard. and then there's the pseudo-devices, where a device driver is out here emulating a device in software with zero underlying hardware. the classic icon of that class? /dev/mem — a mechanism whereby physical memory can be accessed using file access semantics. she's fake but she's serving 🎀

the device abstraction generally provides a common set of system calls, which get dispatched to the corresponding device driver by the upper layers of the kernel. the menu of syscalls available for devices is picked from open(2), close(2), read(2), write(2), ioctl(2), select(2), and mmap(2). not all drivers implement all system calls — like, calling mmap(2) on a keyboard device is not likely to be useful. bestie. why would you. 😭

aspects of the device abstraction have changed significantly in FreeBSD over the past two decades. the section “Historical Notes” (scroll down, she's below) describes some of the more important differences. no cap.

🌈 Accessing Devices

most of the devices in FreeBSD are accessed through device nodes, sometimes also called special files. they live inside instances of the devfs(5) filesystem, which is conventionally mounted on the directory /dev in the file system hierarchy (see also hier(7)). yeah, that /dev. the one you keep peeking into.

the devfs(5) filesystem creates or removes device nodes automatically according to the physical hardware recognized as present at any given time. and for pseudo-devices, device nodes may be created and removed dynamically as required, depending on the nature of the device. she's self-sufficient, we love that for her ✨

access restrictions to device nodes are usually subject to the regular file permissions of the device node entry, instead of being enforced directly by the drivers in the kernel. BUT — and this is the important part — since device nodes are not stored persistently between reboots, those file permissions are set at boot time from rules specified in devfs.conf(5), or dynamically according to rules defined in devfs.rules(5) or set using the devfs(8) command. in that latter case, different rules may be used to make different sets of devices visible within different instances of the devfs(5) filesystem, which may be used, for example, to prevent jailed subsystems from accessing unsafe devices. manual changes to device node permissions may still be made, but will not persist. so don't come crying to me at 3am, okay? 💀

🦋 Drivers without device nodes

drivers for network devices do not use device nodes in order to be accessed. nope. their selection is based on other decisions inside the kernel, and instead of calling open(2), use of a network device is generally introduced by using the system call socket(2). different entry point, same main character energy 👑

🎀 Configuring a driver into the kernel

for each kernel, there is a configuration file that's used as a base to select the facilities and drivers for that kernel, and to tune several options. see config(8) for a detailed description of the files involved. the individual manual pages in this section provide a sample line for the configuration file in their synopsis portions — that's why every page here has that lil stanza up top, iykyk. see also the files /usr/src/sys/conf/NOTES and /usr/src/sys/${ARCH}/conf/NOTES. 📝

drivers need not be statically compiled into the kernel; they may also be loaded as modules, in which case any device nodes they provide will appear only after the module is loaded (and has attached to suitable hardware, if applicable). so like, patience. she'll show up when she's ready. 🙈

💜 Historical Notes

sit down, storytime. 🍓

• Prior to FreeBSD 6.0, device nodes could be created in the traditional way as persistent entries in the file system. while such entries can still be created, they no longer function to access devices. so cute, so useless.
• Prior to FreeBSD 5.0, devices for disk and tape drives existed in two variants, known as block and character devices — or, to use better terms, buffered and unbuffered (raw) devices. the traditional names are reflected by the letters “b” and “c” as the file type identification in the output of ls -l. raw devices were traditionally named with a prefix of “r” — for example /dev/rda0 would denote the raw version of the disk whose buffered device was /dev/da0. this is no longer the case; all disk devices are now “raw” in the traditional sense, even though they are not given “r” prefixes, and “buffered” devices no longer exist at all. rest in peace queen 💀🕊️
• buffered devices were accessed through a buffer cache maintained by the operating system; historically this was the system's primary disk cache, but in FreeBSD this was rendered obsolete by the introduction of unified virtual memory management. buffered devices could be read or written at any byte position, with the buffer mechanism handling the reading and writing of disk blocks. in contrast, raw disk devices can be read or written only at positions and lengths that are multiples of the underlying device block size, and write(2) calls are synchronous — not returning to the caller until the data has been handed off to the device. so yeah, mind your alignment bestie, she's strict. ✨

---

👀 SEE ALSO 👀

close(2), ioctl(2), mmap(2), open(2), read(2), select(2), socket(2), write(2), devfs(5), hier(7), config(8)

---

⭐ HISTORY ⭐

this manual page first appeared in FreeBSD 2.1. an elder. a legend. we stan an OG 🫶

---

💖 AUTHORS 💖

this man page has been rewritten by Andrew Gierth from an earlier version written by Jörg Wunsch with initial input by David E. O'Brien. shoutout to the whole squad, the collab ate 🔥

---

and that's the page!! this one came to you from the Debian camp — dated April 3, 2019 — and it's filed as INTRO(4). mwah, go read the rest of section 4 now, you're literally a kernel girlie now 💅✨🎀