Tribblix: 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.