Intro —
introduction to kernel concepts, device drivers, functions,
and structures
Section 9 of the manual is documentation for concepts in the
broader kernel, including writing device drivers. The manual is organized
into different sections, each of which focuses on a particular area such as
chapter 9E which covers device driver entry points. The following chapters
of section 9 exist:
- Section 9
- The base section 9 (no chapter suffix) contains various high-level
concepts about the kernel. In addition to this page, there are manuals
that cover:
- iports, phymaps, and tgtmaps
- iport(9) discusses the design of
abstractions that are used for host bus adapter (HBA) drivers to aid
in the enumeration of devices.
- vmem
- vmem(9) discusses the design of
the virtual memory allocator that is used throughout the system.
- Section 9E
- Section 9E, driver entry points, describes the interfaces that a loadable
kernel module and device driver need to implement to interface with the
broader kernel. There are discussions of specific frameworks for different
classes of drivers, such as mac(9E)
for networking device drivers, discussions of specific functions that a
given device might implement like
open(9E) which correspond to
performing a traditional operation on the device, and required entry
points for all modules like
_init(9E).
Intro(9E) provides an
overview of loadable kernel modules, device drivers, and which function
families are used for which types of devices.
- Section 9F
- Section 9F, kernel functions, describes the various kernel functions that
are available. The majority of these functions are part of the device
driver interface and have API and ABI guarantees associated with them.
Entry points run the gamut from dealing with memory allocation, to common
data structures, to device driver frameworks (e.g. functions specific to
Networking, USB, SCSI, etc. drivers), to common C functions around
strings, atomics, and memory copying.
Intro(9F) discusses the
different groups of functions that are available and how they are often
used.
- Section 9P
- Section 9P, properties, are used to document various properties that a
device driver may set on themselves. These properties are generally used
in tandem with a driver's
driver.conf(5) or set while the
driver is executing.
- Section 9S
- Section 9S, structures, describes various structures that are filled out,
their members, and their meanings that are used throughout the kernel.
This includes various types like the mblk_t which is
used to transfer data in the networking and USB stacks, the
uio_t which is used to describe an I/O request, and
the cb_ops which all character device drivers fill
out to indicate which operations they support.
Intro(9S) describes the
organization of the different structure types that exist. If exploring a
subsystem, it is generally better to start with the corresponding 9E and
9F discussions which often have more context for how these structures
are used.
Throughout the manuals you may see reference to the term
“DDI” which is the Device Driver Interface, which represents
the committed interfaces that the operating system exports for such
purposes. Note, not everything documented is classified as a committed
interface. Some uncommitted interfaces are documented to aid developers. In
addition to these manuals, there is additional documentation in the form of
various books available at
https://illumos.org/books.
In particular, the following books can be useful for writing software and
debugging:
- Dynamic Tracing Guide
- This introduces and discusses how to use DTrace, the dynamic tracing
facility built into the operating system. DTrace is used with the
dtrace(8) utility.
- Modular Debugger Guide
- This introduces and discusses how to use the modular debugger, which
provides the ability to debug not only user processes, but both the kernel
and crash dumps. To start debugging the kernel, use the
-k flag to
mdb(1).
- Writing Device Drivers
- This introduces how to write device drivers in the system and provides
additional background and more guided tours of various types of devices
and concepts such as DMA allocation.