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 9 16.Os 17.Sh NAME 18.Nm Intro 19.Nd introduction to kernel concepts, device drivers, functions, and structures 20.Sh DESCRIPTION 21Section 9 of the manual is documentation for concepts in the broader kernel, 22including writing device drivers. 23The manual is organized into different sections, each of which focuses on a 24particular area such as chapter 9E which covers device driver entry points. 25The following chapters of section 9 exist: 26.Bl -tag -width Ds 27.It Section 9 28The base section 9 29.Pq no chapter suffix 30contains various high-level concepts about the kernel. 31In addition to this page, there are manuals that cover: 32.Bl -tag -width Ds 33.It iports, phymaps, and tgtmaps 34.Xr iport 9 35discusses the design of abstractions that are used for host bus adapter 36.Pq HBA 37drivers to aid in the enumeration of devices. 38.It vmem 39.Xr vmem 9 40discusses the design of the virtual memory allocator that is used throughout the 41system. 42.El 43.It Section 9E 44Section 9E, driver entry points, describes the interfaces that a loadable kernel 45module and device driver need to implement to interface with the broader kernel. 46There are discussions of specific frameworks for different classes of drivers, 47such as 48.Xr mac 9E 49for networking device drivers, discussions of specific functions that a given 50device might implement like 51.Xr open 9E 52which correspond to performing a traditional operation on the device, and 53required entry points for all modules like 54.Xr _init 9E . 55.Pp 56.Xr Intro 9E 57provides an overview of loadable kernel modules, device drivers, and which 58function families are used for which types of devices. 59.It Section 9F 60Section 9F, kernel functions, describes the various kernel functions that are 61available. 62The majority of these functions are part of the device driver interface and have 63API and ABI guarantees associated with them. 64Entry points run the gamut from dealing with memory allocation, to common data 65structures, to device driver frameworks 66.Pq e.g. functions specific to Networking, USB, SCSI, etc. drivers , 67to common C functions around strings, atomics, and memory copying. 68.Pp 69.Xr Intro 9F 70discusses the different groups of functions that are available and how they are 71often used. 72.It Section 9P 73Section 9P, properties, are used to document various properties that a device 74driver may set on themselves. 75These properties are generally used in tandem with a driver's 76.Xr driver.conf 5 77or set while the driver is executing. 78.It Section 9S 79Section 9S, structures, describes various structures that are filled out, their 80members, and their meanings that are used throughout the kernel. 81This includes various types like the 82.Vt mblk_t 83which is used to transfer data in the networking and USB stacks, the 84.Vt uio_t 85which is used to describe an I/O request, and the 86.Vt cb_ops 87which all character device drivers fill out to indicate which operations they 88support. 89.Pp 90.Xr Intro 9S 91describes the organization of the different structure types that exist. 92If exploring a subsystem, it is generally better to start with the corresponding 939E and 9F discussions which often have more context for how these structures are 94used. 95.El 96.Pp 97Throughout the manuals you may see reference to the term 98.Dq DDI 99which is the Device Driver Interface, which represents the committed interfaces 100that the operating system exports for such purposes. 101Note, not everything documented is classified as a committed interface. 102Some uncommitted interfaces are documented to aid developers. 103In addition to these manuals, there is additional documentation in the form of 104various books available at 105.Lk https://illumos.org/books . 106In particular, the following books can be useful for writing software and 107debugging: 108.Bl -tag -width Ds 109.It Dynamic Tracing Guide 110This introduces and discusses how to use DTrace, the dynamic tracing facility 111built into the operating system. 112DTrace is used with the 113.Xr dtrace 8 114utility. 115.It Modular Debugger Guide 116This introduces and discusses how to use the modular debugger, which provides 117the ability to debug not only user processes, but both the kernel and crash 118dumps. 119To start debugging the kernel, use the 120.Fl k 121flag to 122.Xr mdb 1 . 123.It Writing Device Drivers 124This introduces how to write device drivers in the system and provides 125additional background and more guided tours of various types of devices and 126concepts such as DMA allocation. 127.El 128.Sh SEE ALSO 129.Xr iport 9 , 130.Xr vmem 9 , 131.Xr Intro 9E , 132.Xr Intro 9F , 133.Xr Intro 9P , 134.Xr Intro 9S 135