1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd April 28, 2024 15.Dt INTRO 9S 16.Os 17.Sh NAME 18.Nm Intro 19.Nd introduction to kernel data structures 20.Sh DESCRIPTION 21Section 9S describes the data structures that are used by the kernel and 22the various device driver frameworks. 23The structure manual pages should generally be considered documentation 24for the structure itself and the companions in sections 9, 9E, and 9F, 25provide more of the surrounding context. 26.Pp 27The structures listed here have varying ABI guarantees. 28While the majority of structures documented here are part of committed 29interfaces, that is not true of all of them. 30Uncommitted structures have no ABI guarantees and may change at any 31time. 32They are documented to aid folks working on the system. 33.Pp 34The rest of this manual groups documented structures into categories 35with additional information about what to read for more information. 36.Ss Module and Driver Initialization 37The structures here are all fundamental to initializing a device driver. 38See 39.Xr Intro 9E 40for more on their use and the examples in 41.Xr _init 9E 42for more information. 43These structures are generally required for every kernel module. 44.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 45.It Xr cb_ops 9S Ta Xr dev_ops 9S 46.It Xr modldrv 9S Ta Xr modlinkage 9S 47.It Xr modlmisc 9S Ta Xr modlstrmod 9S 48.El 49.Ss Character and Block I/O 50These structures are used as part of the fundamental units of performing 51I/O for character and block devices and are related to how a driver will 52implement the corresponding 53.Xr read 9E , 54.Xr write 9E , 55and 56.Xr strategy 9E 57entry points. 58.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 59.It Xr aio_req 9S Ta Xr buf 9S 60.It Xr iovec 9S Ta Xr uio 9S 61.El 62.Ss Message Block Structures 63Message blocks, 64.Vt mblk_t , 65are the fundamental building block of networking, USB, and STREAMS 66device drivers. 67An overview to their design and structure can be found in the 68.Sy Message Block Functions 69of 70.Xr Intro 9F . 71The data for a message block is generally found in a corresponding data 72block structure. 73The following structures are relevant: 74.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 75.It Xr dblk 9S Ta Xr free_rtn 9S 76.It Xr mblk 9S Ta 77.El 78.Ss DMA Related Structures 79Direct Memory Access is one of the primary things that most device 80drivers facilitate. 81See 82.Xr Intro 9F 83for more on DMA itself and how these structures fit into those 84functions. 85.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 86.It Xr ddi_device_acc_attr 9S Ta Xr ddi_dma_attr 9S 87.It Xr ddi_dma_cookie 9S Ta Xr ddi_dmae_req 9S 88.El 89.Ss MAC Related Structures 90The following structures are all part of the 91.Xr mac 9E 92device driver framework that is used for networking device drivers. 93See 94.Xr mac 9E 95for more information on how they fit in. 96Networking device drivers use the 97.Sx Message Blocks 98related data structures for I/O purposes. 99These structures describe specific parts of interfacing with the MAC 100framework. 101.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 102.It Xr mac_callbacks 9S Ta Xr mac_group_info 9S 103.It Xr mac_intr 9S Ta Xr mac_register 9S 104.It Xr mac_ring_info 9S Ta 105.El 106.Ss SCSA Related Structures 107These structures are part of the SCSI/SAS device driver framework and 108are used in implementing device drivers for host bus adapters 109.Pq HBAs . 110.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 111.It Xr scsi_address 9S Ta Xr scsi_arq_status 9S 112.It Xr scsi_asc_key_strings 9S Ta Xr scsi_device 9S 113.It Xr scsi_extended_sense 9S Ta Xr scsi_hba_tran 9S 114.It Xr scsi_inquiry 9S Ta Xr scsi_pkt 9S 115.It Xr scsi_status 9S Ta 116.El 117.Ss Kernel Statistics 118Kernel statistics, or kstats, are a means for communicating data to 119userland through the 120.Xr kstat 4D 121driver, 122.Xr libkstat 3LIB 123library, and 124.Xr kstat 8 125command. 126Drivers can create their own kstats through the use of 127.Xr kstat_create 9F 128and some device driver frameworks create and manage kstats on behalf of 129drivers. 130The root kstat structure is discussed in 131.Xr kstat 9S . 132The other manuals listed discuss the different types of kstats that 133exist. 134.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 135.It Xr kstat_intr 9S Ta Xr kstat_io 9S 136.It Xr kstat_named 9S Ta Xr kstat 9S 137.El 138.Ss Miscellaneous Device Driver Interfaces 139The following structures are all related to the broader device driver 140interface and serve different parts of it. 141They cover memory mapping, error handling, interrupts, etc. 142.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 143.It Xr ddi_fm_error 9S Ta Xr ddi_idevice_cookie 9S 144.It Xr devmap_callback_ctl 9S Ta 145.El 146.Ss STREAMS Related Structures 147These structures include the fundamental structures required for 148registering a STREAMS based device driver with the kernel as well as the 149different structures, such as the 150.Xr copyreq 9S , 151that are used as part of handling specific classes of operations. 152The 153.Xr queue 9S 154is the fundamental building block of STREAMS communication. 155Like with networking device drivers, STREAMS drivers also leverage the 156.Sx Message Blocks 157data structures for communication. 158.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 159.It Xr copyreq 9S Ta Xr copyresp 9S 160.It Xr fmodsw 9S Ta Xr iocblk 9S 161.It Xr linkblk 9S Ta Xr module_info 9S 162.It Xr qband 9S Ta Xr qinit 9S 163.It Xr queclass 9S Ta Xr queue 9S 164.It Xr streamtab 9S Ta Xr stroptions 9S 165.El 166.Ss Network Hooks 167Network hooks provide a way for firewalls to participate and manipulate 168packets as they flow through the system. 169The following structures are related to the network hooks interfaces. 170.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 171.It Xr hook_nic_event 9S Ta Xr hook_pkt_event 9S 172.It Xr hook_t 9S Ta Xr net_inject_t 9S 173.It Xr net_instance_t 9S Ta 174.El 175.Ss Historical Structures 176The following structures correspond to subsystems that generally are no 177longer used 178.Po 179.Xr mac 9E 180aka GLDv3 has replaced the GLDv2 functions mentioned below 181.Pc 182or refer to hardware that is no longer commonly found. 183.Bl -column -offset -indent "mac_capab_transceiver" "mac_capab_transceiver" 184.It Xr gld_mac_info 9S Ta Xr gld_stats 9S 185.It Xr tuple 9S Ta 186.El 187.Ss Manual Organization 188In addition to the standard manual sections that exist, entries in 9S 189contain an additional section titled 190.Dq STRUCTURE MEMBERS . 191This enumerates and describes the different members of the structures, 192their types, their purposes, and any constraints on when they should be 193used or how they should be interpreted. 194.Sh SEE ALSO 195.Xr Intro 9 , 196.Xr Intro 9E , 197.Xr Intro 9F 198