.\"     $NetBSD: intro.9,v 1.24.2.2 2019/09/05 08:19:41 martin Exp $
.\"
.\" Copyright (c) 1997, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jeremy Cooper, and Mindaugas Rasiukevicius.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 14, 2018
.Dt INTRO 9
.Os
.Sh NAME
.Nm intro
.Nd introduction to kernel internals
.Sh DESCRIPTION
This section contains information related to the internal operation of the
system kernel.
It describes function interfaces and variables of use to the systems and device
driver programmer.
.Pp
In addition to the normal man page format, the kernel pages include an
additional section:
.Bl -tag -width "CODE REFERENCES"
.It "CODE REFERENCES"
Contains the pathname(s) of the source file(s) which contain the definition
and/or source code of the variables or functions being documented.
Any paths are relative to the top level of the source tree (traditionally
.Pa /usr/src ) .
.El
.Sh MEMORY MANAGEMENT
Introduction to kernel memory allocators.
See
.Xr memoryallocators 9 .
.Pp
Machine-dependent portion of the virtual memory system.
See
.Xr pmap 9 .
.Pp
Virtual memory system external interface.
See
.Xr uvm 9 .
.Sh I/O SUBSYSTEM
Buffer cache interfaces.
See
.Xr buffercache 9 .
.Pp
Device buffer queues.
See
.Xr bufq 9 .
.Pp
Initiate I/O on raw devices.
See
.Xr physio 9 .
.Pp
I/O descriptor allocation interface.
See
.Xr getiobuf 9 .
.Sh PROCESS CONTROL
Idle CPU while waiting for work.
See
.Xr cpu_idle 9 .
.Pp
Finish a fork operation.
See
.Xr cpu_lwp_fork 9 .
.Pp
Switch to another light weight process.
See
.Xr mi_switch 9 .
.Pp
Current process and processor.
See
.Xr curproc 9 .
.Pp
Set process uid and gid.
See
.Xr do_setresuid 9 .
.Pp
New processes and kernel threads.
See
.Xr fork1 9 ,
.Xr kthread 9 .
.Pp
Context switch notification.
See
.Xr cpu_need_resched 9 .
.Pp
Common scheduler framework.
See
.Xr csf 9 .
.Pp
Software signal facilities.
See
.Xr signal 9 .
.Pp
Suspend the scheduler.
See
.Xr suspendsched 9 .
.Pp
Return path to user-mode execution.
See
.Xr userret 9 .
.Sh FILE SYSTEM
High-level file operations.
See
.Xr dofileread 9 .
.Pp
Convert an extended attribute namespace identifier to a string and
vice versa.
See
.Xr extattr 9 .
.Pp
Operations on file entries.
See
.Xr file 9 .
.Pp
In-kernel, file system independent, file-meta data association.
See
.Xr fileassoc 9 .
.Pp
File descriptor tables and operations.
See
.Xr filedesc 9 .
.Pp
File descriptor owner handling functions.
See
.Xr fsetown 9 .
.Pp
File system suspension helper subsystem.
See
.Xr fstrans 9 .
.Pp
Pathname lookup, cache and management.
See
.Xr namei 9 ,
.Xr namecache 9 .
.Pp
Kernel interface to file systems.
See
.Xr vfs 9 .
.Pp
Kernel representation of a file or directory and vnode attributes.
See
.Xr vnode 9 ,
.Xr vattr 9 .
.Sh NETWORKING
Kernel interfaces for manipulating output queues on network interfaces.
See
.Xr altq 9 .
.Pp
Externally visible ARP functions.
See
.Xr arp 9 .
.Pp
Ethernet and FDDI driver support functions and macros.
See
.Xr ethersubr 9 .
.Pp
Core 802.11 network stack functions and rate adaptation based on
received signal strength.
See
.Xr ieee80211 9 ,
.Xr rssadapt 9 .
.Pp
Compute Internet checksum.
See
.Xr in_cksum 9 .
.Pp
Look up the IPv4 source address best matching an IPv4 destination.
See
.Xr in_getifa 9 .
.Pp
Functions and macros for managing memory used by networking code.
See
.Xr mbuf 9 .
.Pp
Packet filter interface.
See
.Xr pfil 9 .
.Pp
Route callout functions.
See
.Xr rt_timer 9 .
.Pp
TCP congestion control API.
See
.Xr tcp_congctl 9 .
.Sh LOCKING AND INTERRUPT CONTROL
See
.Xr locking 9
for an overview.
.Pp
Condition variables.
See
.Xr condvar 9 .
.Pp
Kernel lock functions.
See
.Xr lock 9 .
.Pp
Memory barriers.
See
.Xr membar_ops 3 .
.Pp
Mutual exclusion primitives.
See
.Xr mutex 9 .
.Pp
Restartable atomic sequences.
See
.Xr ras 9 .
.Pp
Reader / writer lock primitives.
See
.Xr rwlock 9 .
.Pp
Machine-independent software interrupt framework.
See
.Xr softint 9 .
.Pp
Functions to modify system interrupt priority level.
See
.Xr spl 9 .
.Pp
Functions to raise the system priority level.
See
.Xr splraiseipl 9 .
.Sh SECURITY
Kernel authorization framework.
See
.Xr kauth 9 .
.Pp
API for cryptographic services in the kernel.
See
.Xr opencrypto 9 .
.Pp
Security model development guidelines.
See
.Xr secmodel 9 .
.Sh SYSTEM TIME CONTROL
Execute a function after a specified length of time.
See
.Xr callout 9 .
.Pp
Microsecond delay.
See
.Xr delay 9 .
.Pp
Real-time timer.
See
.Xr hardclock 9 .
.Pp
System clock frequency.
See
.Xr hz 9 .
.Pp
Initialization of system time and time-of-day clock support.
See
.Xr inittodr 9 ,
.Xr todr 9 .
.Pp
Check that a timeval value is valid, and correct.
See
.Xr itimerfix 9 .
.Pp
System time variables.
See
.Xr timecounter 9 .
.Pp
Realtime system clock.
See
.Xr microtime 9 .
.Pp
Get the time elapsed since boot.
See
.Xr microuptime 9 .
.Pp
Convert milliseconds to system clock ticks.
See
.Xr mstohz 9 .
.Pp
Function to help implement rate-limited actions.
See
.Xr ppsratecheck 9 .
.Pp
Function to help implement rate-limited actions.
See
.Xr ratecheck 9 .
.Pp
Set battery-backed clock from system time.
See
.Xr resettodr 9 .
.Pp
System time variables.
See
.Xr time_second 9 .
.Sh KERNEL AND USER SPACE DATA COPY FUNCTIONS
Kernel space to/from user space copy functions.
See
.Xr copy 9 .
.Pp
Store data to user-space.
See
.Xr ustore 9 .
.Pp
Fetch data from user-space.
See
.Xr ufetch 9 .
.Pp
Move data described by a struct uio.
See
.Xr uiomove 9 .
.Sh MACHINE DEPENDENT KERNEL FUNCTIONS
Machine-dependent clock setup interface.
See
.Xr cpu_initclocks 9 .
.Pp
Machine-dependent process core dump interface.
See
.Xr cpu_coredump 9 .
.Pp
Machine-dependent kernel core dumps.
See
.Xr cpu_dumpconf 9 .
.Pp
Unique CPU identification number
See
.Xr cpu_number 9 .
.Pp
Halt or reboot the system
See
.Xr cpu_reboot 9 .
.Pp
Machine-dependent root file system setup
See
.Xr cpu_rootconf 9 .
.Pp
Machine-dependent CPU startup
See
.Xr cpu_startup 9 .
.Pp
Disk label management routines.
See
.Xr disklabel 9 .
.Sh DEVICE CONFIGURATION
Autoconfiguration frame-work.
See
.Xr autoconf 9 .
.Pp
Description of a device driver.
See
.Xr driver 9 .
.Pp
The autoconfiguration framework ``device definition'' language.
See
.Xr config 9 .
.Pp
Machine-dependent device autoconfiguration.
See
.Xr cpu_configure 9 .
.Sh MI DEVICE DRIVER API
Bus and Machine Independent DMA Mapping Interface.
See
.Xr bus_dma 9 .
.Pp
Bus space manipulation functions.
See
.Xr bus_space 9 .
.Pp
Generic disk framework.
See
.Xr disk 9 .
.Pp
Hardware-assisted data mover interface.
See
.Xr dmover 9 .
Generic event counter framework.
See
.Xr evcnt 9 .
.Pp
Firmware loader API for device drivers.
See
.Xr firmload 9 .
.Pp
How to implement a new ioctl call to access device drivers.
See
.Xr ioctl 9 .
.Pp
Extensible line discipline framework.
See
.Xr linedisc 9 .
.Sh CONSOLE DEVICES
Console magic key sequence management.
See
.Xr cnmagic 9 .
.Pp
Console access interface.
See
.Xr cons 9 .
.Pp
Raster display operations.
See
.Xr rasops 9 .
.Pp
Generic virtual console framework.
See
.Xr vcons 9 .
.Pp
Machine-independent console support.
See
.Xr wscons 9 .
.Sh DEVICE SPECIFIC IMPLEMENTATION
Interface between low and high level audio drivers.
See
.Xr audio 9 .
.Pp
Bluetooth Device/Protocol API.
See
.Xr bluetooth 9 .
.Pp
Support for CardBus PC-Card devices.
See
.Xr cardbus 9 .
.Pp
VESA Display Data Channel V2.
See
.Xr ddc 9 .
.Pp
VESA Extended Display Identification Data.
See
.Xr edid 9 .
.Pp
Inter IC (I2C) bus.
See
.Xr iic 9 .
.Pp
Baseboard I/O control ASIC for DEC TURBOchannel systems.
See
.Xr ioasic 9 .
.Pp
Industry-standard Architecture.
See
.Xr isa 9 .
.Pp
Introduction to ISA Plug-and-Play support.
See
.Xr isapnp 9 .
.Pp
MicroChannel Architecture bus.
See
.Xr mca 9 .
.Pp
PPBUS microseqencer developer's guide.
See
.Xr microseq 9 .
.Pp
Peripheral Component Interconnect.
See
.Xr pci 9 .
.Pp
Perform PCI bus configuration.
See
.Xr pci_configure_bus 9 .
.Pp
PCI bus interrupt manipulation functions.
See
.Xr pci_intr 9 .
.Pp
PC keyboard port interface.
See
.Xr pckbport 9 .
.Pp
Support for PCMCIA PC-Card devices.
See
.Xr pcmcia 9 .
.Pp
Interface between low and high level radio drivers.
See
.Xr radio 9 .
.Pp
Functions to make a device available for entropy collection.
See
.Xr rnd 9 .
.Pp
SCSI/ATAPI middle-layer interface.
See
.Xr scsipi 9 .
.Pp
TURBOchannel bus.
See
.Xr tc 9 .
.Pp
USB tty support.
See
.Xr ucom 9 .
.Pp
USB device drivers interface.
See
.Xr usbdi 9 .
.Pp
Versa Module Euroboard bus.
See
.Xr vme 9 .
.Pp
Machine-independent IDE/ATAPI driver.
See
.Xr wdc 9 .
.Sh KERNEL EVENT
Functions to add or remove kernel event filters.
See
.Xr kfilter_register 9 .
.Pp
Functions to raise kernel event.
See
.Xr knote 9 .
.Pp
Record and wakeup select requests.
See
.Xr selrecord 9 .
.Pp
Simple do-it-in-thread-context framework.
See
.Xr workqueue 9 .
.Sh KERNEL HELPER FUNCTIONS
Kernel expression verification macros.
See
.Xr KASSERT 9 .
.Pp
Convert a single byte between (unsigned) packed bcd and binary.
See
.Xr bcdtobin 9 .
.Pp
Bitmask output conversion.
See
.Xr snprintb 3 .
.Pp
General purpose extent manager.
See
.Xr extent 9 .
.Pp
Compare integers.
See
.Xr imax 9 .
.Pp
Kernel formatted output conversion.
See
.Xr kprintf 9 .
.Pp
Data comparing, moving, copying, setting and cleaning.
See
.Xr memcmp 9 ,
.Xr memmove 9 ,
.Xr memcpy 9 ,
.Xr memset 9 ,
.Xr bcmp 9 ,
.Xr bcopy 9 ,
.Xr bzero 9 ,
.Xr kcopy 9 .
.Pp
Log a message from the kernel through the /dev/klog device.
See
.Xr log 9 .
.Pp
Bring down system on fatal error.
See
.Xr panic 9 .
.Sh MISC
Power management and inter-driver messaging.
See
.Xr pmf 9 .
.Pp
Run all shutdown hooks.
See
.Xr pmf_system_shutdown 9 .
.Pp
Kernel internal error numbers.
See
.Xr errno 9 .
.Pp
Kernel hash functions, hash table construction and destruction.
See
.Xr hash 9 ,
.Xr hashinit 9 .
.Pp
Format a number into a human readable form.
See
.Xr humanize_number 9 .
.Pp
Options string management.
See
.Xr optstr 9 .
.Pp
Performs pattern matching on strings.
See
.Xr pmatch 9 .
.Pp
Add or remove a shutdown hook.
See
.Xr pmf 9 .
.Pp
Non-local jumps.
See
.Xr setjmp 9 .
.Pp
System variable control interfaces.
See
.Xr sysctl 9 .
.Sh HISTORY
The
.Nx
kernel internals section first appeared in
.Nx 1.2 .