illumos: manual page: Intro.9

INTRO(9) Kernel Concepts INTRO(9)

NAME

Intro - introduction to kernel concepts, device drivers, functions, and
structures

DESCRIPTION

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.

NAME

DESCRIPTION

SEE ALSO