illumos: manual page: Intro.9s

INTRO(9S) Data Structures for Drivers INTRO(9S)

NAME

Intro - introduction to kernel data structures

DESCRIPTION

Section 9S describes the data structures that are used by the kernel and
the various device driver frameworks. The structure manual pages should
generally be considered documentation for the structure itself and the
companions in sections 9, 9E, and 9F, provide more of the surrounding
context.

The structures listed here have varying ABI guarantees. While the majority
of structures documented here are part of committed interfaces, that is not
true of all of them. Uncommitted structures have no ABI guarantees and may
change at any time. They are documented to aid folks working on the
system.

The rest of this manual groups documented structures into categories with
additional information about what to read for more information.

Module and Driver Initialization

The structures here are all fundamental to initializing a device driver.
See Intro(9E) for more on their use and the examples in _init(9E) for more
information. These structures are generally required for every kernel
module.

cb_ops(9S) dev_ops(9S)
modldrv(9S) modlinkage(9S)
modlmisc(9S) modlstrmod(9S)

Character and Block I/O
These structures are used as part of the fundamental units of performing
I/O for character and block devices and are related to how a driver will
implement the corresponding read(9E), write(9E), and strategy(9E) entry
points.

aio_req(9S) buf(9S)
iovec(9S) uio(9S)

Message Block Structures

Message blocks, mblk_t, are the fundamental building block of networking,
USB, and STREAMS device drivers. An overview to their design and structure
can be found in the Message Block Functions of Intro(9F). The data for a
message block is generally found in a corresponding data block structure.
The following structures are relevant:

dblk(9S) free_rtn(9S)
mblk(9S)

DMA Related Structures

Direct Memory Access is one of the primary things that most device drivers
facilitate. See Intro(9F) for more on DMA itself and how these structures
fit into those functions.

ddi_device_acc_attr(9S) ddi_dma_attr(9S)
ddi_dma_cookie(9S) ddi_dmae_req(9S)

MAC Related Structures

The following structures are all part of the mac(9E) device driver
framework that is used for networking device drivers. See mac(9E) for more
information on how they fit in. Networking device drivers use the Message
Blocks related data structures for I/O purposes. These structures describe
specific parts of interfacing with the MAC framework.

mac_callbacks(9S) mac_group_info(9S)
mac_intr(9S) mac_register(9S)
mac_ring_info(9S)

SCSA Related Structures

These structures are part of the SCSI/SAS device driver framework and are
used in implementing device drivers for host bus adapters (HBAs).

scsi_address(9S) scsi_arq_status(9S)
scsi_asc_key_strings(9S) scsi_device(9S)
scsi_extended_sense(9S) scsi_hba_tran(9S)
scsi_inquiry(9S) scsi_pkt(9S)
scsi_status(9S)

Kernel Statistics

Kernel statistics, or kstats, are a means for communicating data to
userland through the kstat(4D) driver, libkstat(3LIB) library, and kstat(8)
command. Drivers can create their own kstats through the use of
kstat_create(9F) and some device driver frameworks create and manage kstats
on behalf of drivers. The root kstat structure is discussed in kstat(9S).
The other manuals listed discuss the different types of kstats that exist.

kstat_intr(9S) kstat_io(9S)
kstat_named(9S) kstat(9S)

Miscellaneous Device Driver Interfaces

The following structures are all related to the broader device driver
interface and serve different parts of it. They cover memory mapping,
error handling, interrupts, etc.

ddi_fm_error(9S) ddi_idevice_cookie(9S)
devmap_callback_ctl(9S)

STREAMS Related Structures

These structures include the fundamental structures required for
registering a STREAMS based device driver with the kernel as well as the
different structures, such as the copyreq(9S), that are used as part of
handling specific classes of operations. The queue(9S) is the fundamental
building block of STREAMS communication. Like with networking device
drivers, STREAMS drivers also leverage the Message Blocks data structures
for communication.

copyreq(9S) copyresp(9S)
fmodsw(9S) iocblk(9S)
linkblk(9S) module_info(9S)
qband(9S) qinit(9S)
queclass(9S) queue(9S)
streamtab(9S) stroptions(9S)

Network Hooks

Network hooks provide a way for firewalls to participate and manipulate
packets as they flow through the system. The following structures are
related to the network hooks interfaces.

hook_nic_event(9S) hook_pkt_event(9S)
hook_t(9S) net_inject_t(9S)
net_instance_t(9S)

Historical Structures

The following structures correspond to subsystems that generally are no
longer used (mac(9E) aka GLDv3 has replaced the GLDv2 functions mentioned
below) or refer to hardware that is no longer commonly found.

gld_mac_info(9S) gld_stats(9S)
tuple(9S)

Manual Organization

In addition to the standard manual sections that exist, entries in 9S
contain an additional section titled "STRUCTURE MEMBERS". This enumerates
and describes the different members of the structures, their types, their
purposes, and any constraints on when they should be used or how they
should be interpreted.