--- name: "intro" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/intro/9" --- # intro(9) introduction to kernel programming interfaces ## NAME **intro** – introduction to kernel programming interfaces ## DESCRIPTION Welcome to the FreeBSD kernel documentation. Outside the source code itself, this set of [man(1)](/man/1.md) pages is the primary resource for information on usage of the numerous programming interfaces available within the kernel. In some cases, it is also a source of truth for the implementation details and/or design decisions behind a particular subsystem or piece of code. The intended audience of this documentation is developers, and the primary authors are also developers. It is written assuming a certain familiarity with common programming or OS-level concepts and practices. However, this documentation should also attempt to provide enough background information that readers approaching a particular subsystem or interface for the first time will be able to understand. To further set expectations, we acknowledge that kernel documentation, like the source code itself, is forever a work-in-progress. There will be large sections of the codebase whose documentation is subtly or severely outdated, or missing altogether. This documentation is a supplement to the source code, and cannot always be taken at face value. At its best, section 9 documentation will provide a description of a particular piece of code that, paired with its implementation, fully informs the reader of the intended and realized effects. [man(1)](/man/1.md) pages in this section most frequently describe functions, but may also describe types, global variables, macros, or high-level concepts. ## CODING GUIDELINES Code written for the FreeBSD kernel is expected to conform to the established style and coding conventions. Please see [style(9)](/style/9.md) for a detailed set of rules and guidelines. ## OVERVIEW Below is presented various subsystems. ### Data Structures There are implementations for many well-known data structures available in the kernel. - [bitstring(3)](/bitstring/3.md) Simple bitmap implementation. - [counter(9)](/counter/9.md) An SMP-safe general-purpose counter implementation. - [hash(9)](/hash/9.md) Hash map implementation. - [nv(9)](/nv/9.md) Name/value pairs. - [queue(3)](/queue/3.md) Singly-linked and doubly-linked lists, and queues. - [refcount(9)](/refcount/9.md) An SMP-safe implementation of reference counts. - [sbuf(9)](/sbuf/9.md) Dynamic string composition. - [sglist(9)](/sglist/9.md) A scatter/gather list implementation. ### Utility Functions Functions or facilities of general usefulness or convenience. See also the Testing and Debugging Tools or Miscellaneous sub-sections below. Formatted output and logging functions are described by [printf(9)](/printf/9.md). Endian-swapping functions: [byteorder(9)](/byteorder/9.md). Data output in hexadecimal format: [hexdump(9)](/hexdump/9.md). A rich set of macros for declaring [sysctl(8)](/sysctl/8.md) variables and functions is described by [sysctl(9)](/sysctl/9.md). Non-recoverable errors in the kernel should trigger a [panic(9)](/panic/9.md). Run-time assertions can be verified using the [KASSERT(9)](/KASSERT/9.md) macros. Compile-time assertions should use **\_Static\_assert**(). The SYSINIT framework provides macros for declaring functions that will be executed during start-up and shutdown; see [SYSINIT(9)](/SYSINIT/9.md). Deprecation messages may be emitted with [gone\_in(9)](/gone_in/9.md). A unit number facility is provided by [unr(9)](/unr/9.md). ### Synchronization Primitives The [locking(9)](/locking/9.md) man page gives an overview of the various types of locks available in the kernel and advice on their usage. Atomic primitives are described by [atomic(9)](/atomic/9.md). The [epoch(9)](/epoch/9.md) and [smr(9)](/smr/9.md) facilities are used to create lock-free data structures. There is also [seqc(9)](/seqc/9.md). ### Memory Management Dynamic memory allocations inside the kernel are generally done using [malloc(9)](/malloc/9.md). Frequently allocated objects may prefer to use [uma(9)](/uma/9.md). Much of the virtual memory system operates on *vm\_page\_t* structures. The following functions are documented: vm\_page\_advise(9), [vm\_page\_aflag(9)](/vm_page_aflag/9.md), [vm\_page\_alloc(9)](/vm_page_alloc/9.md), [vm\_page\_bits(9)](/vm_page_bits/9.md), [vm\_page\_busy(9)](/vm_page_busy/9.md), [vm\_page\_deactivate(9)](/vm_page_deactivate/9.md), [vm\_page\_free(9)](/vm_page_free/9.md), [vm\_page\_grab(9)](/vm_page_grab/9.md), [vm\_page\_insert(9)](/vm_page_insert/9.md), [vm\_page\_lookup(9)](/vm_page_lookup/9.md), [vm\_page\_rename(9)](/vm_page_rename/9.md), vm\_page\_sbusy(9), [vm\_page\_wire(9)](/vm_page_wire/9.md) Virtual address space maps are managed with the [vm\_map(9)](/vm_map/9.md) API. The machine-dependent portion of the virtual memory stack is the [pmap(9)](/pmap/9.md) module. Allocation policies for NUMA memory domains are managed with the [domainset(9)](/domainset/9.md) API. ### File Systems The kernel interface for file systems is [VFS(9)](/VFS/9.md). File system implementations register themselves with [vfsconf(9)](/vfsconf/9.md). The [vnode(9)](/vnode/9.md) is the abstract and filesystem-independent representation of a file, directory, or other file-like entity within the kernel. The implementation of access control lists for filesystems is described by [acl(9)](/acl/9.md). Also [vaccess(9)](/vaccess/9.md). ### I/O and Storage The GEOM framework represents I/O requests using the [bio(9)](/bio/9.md) structure. Disk drivers connect themselves to GEOM using the [disk(9)](/disk/9.md) API. The [devstat(9)](/devstat/9.md) facility provides an interface for recording device statistics in disk drivers. ### Networking Much of the networking stack uses the [mbuf(9)](/mbuf/9.md), a flexible memory management unit commonly used to store network packets. Network interfaces are implemented using the [ifnet(9)](/ifnet/9.md) API, which has functions for drivers and consumers. A framework for managing packet output queues is described by [altq(9)](/altq/9.md). To receive incoming packets, network protocols register themselves with [netisr(9)](/netisr/9.md). Virtualization of the network stack is provided by [VNET(9)](/VNET/9.md). The front-end for interfacing with network sockets from within the kernel is described by [socket(9)](/socket/9.md). The back-end interface for socket implementations is [domain(9)](/domain/9.md). The low-level packet filter interface is described by [pfil(9)](/pfil/9.md). The [bpf(9)](/bpf/9.md) interface provides a mechanism to redirect packets to userspace. The subsystem for IEEE 802.11 wireless networking is described by [ieee80211(9)](/ieee80211/9.md). A framework for modular TCP implementations is described by [tcp\_functions(9)](/tcp_functions/9.md). A framework for modular congestion control algorithms is described by [mod\_cc(9)](/mod_cc/9.md). ### Device Drivers Consult the [device(9)](/device/9.md) and [driver(9)](/driver/9.md) pages first. Most drivers act as devices, and provide a set of methods implementing the device interface. This includes methods such as [DEVICE\_PROBE(9)](/DEVICE_PROBE/9.md), [DEVICE\_ATTACH(9)](/DEVICE_ATTACH/9.md), and [DEVICE\_DETACH(9)](/DEVICE_DETACH/9.md). In addition to devices, there are buses. Buses may have children, in the form of devices or other buses. Bus drivers will implement additional methods, such as [BUS\_ADD\_CHILD(9)](/BUS_ADD_CHILD/9.md), [BUS\_READ\_IVAR(9)](/BUS_READ_IVAR/9.md), or [BUS\_RESCAN(9)](/BUS_RESCAN/9.md). Buses often perform resource accounting on behalf of their children. For this there is the [rman(9)](/rman/9.md) API. Drivers can request and manage their resources (e.g. memory-space or IRQ number) from their parent using the following sets of functions: [bus\_alloc\_resource(9)](/bus_alloc_resource/9.md), [bus\_adjust\_resource(9)](/bus_adjust_resource/9.md), [bus\_get\_resource(9)](/bus_get_resource/9.md), [bus\_map\_resource(9)](/bus_map_resource/9.md), [bus\_release\_resource(9)](/bus_release_resource/9.md), [bus\_set\_resource(9)](/bus_set_resource/9.md) Direct Memory Access (DMA) is handled using the [busdma(9)](/busdma/9.md) framework. Functions for accessing bus space (i.e. read/write) are provided by [bus\_space(9)](/bus_space/9.md). ### Clocks and Timekeeping The kernel clock frequency and overall system time model is described by [hz(9)](/hz/9.md). A few global time variables, such as system up-time, are described by [time(9)](/time/9.md). Raw CPU cycles are provided by [get\_cyclecount(9)](/get_cyclecount/9.md). ### Userspace Memory Access Direct read/write access of userspace memory from the kernel is not permitted, and memory transactions that cross the kernel/user boundary must go through one of several interfaces built for this task. Most device drivers use the [uiomove(9)](/uiomove/9.md) set of routines. Simpler primitives for reading or writing smaller chunks of memory are described by [casuword(9)](/casuword/9.md), [copy(9)](/copy/9.md), [fetch(9)](/fetch/9.md), and [store(9)](/store/9.md). ### Kernel Threads, Tasks, and Callbacks Kernel threads and processes are created using the [kthread(9)](/kthread/9.md) and [kproc(9)](/kproc/9.md) interfaces, respectively. Where dedicated kernel threads are too heavyweight, there is also the [taskqueue(9)](/taskqueue/9.md) interface. For low-latency callback handling, the [callout(9)](/callout/9.md) framework should be used. Dynamic handlers for pre-defined event hooks are registered and invoked using the [EVENTHANDLER(9)](/EVENTHANDLER/9.md) API. ### Thread Switching and Scheduling The machine-independent interface to a context switch is [mi\_switch(9)](/mi_switch/9.md). To prevent preemption, use a [critical(9)](/critical/9.md) section. To voluntarily yield the processor, use [kern\_yield(9)](/kern_yield/9.md). The various functions which will deliberately put a thread to sleep are described by [sleep(9)](/sleep/9.md). Sleeping threads are removed from the scheduler and placed on a [sleepqueue(9)](/sleepqueue/9.md). ### Processes and Signals To locate a process or process group by its identifier, use [pfind(9)](/pfind/9.md) and [pgfind(9)](/pgfind/9.md). Alternatively, the [pget(9)](/pget/9.md) function provides additional search specificity. The "hold count" of a process can be manipulated with [PHOLD(9)](/PHOLD/9.md). The kernel interface for signals is described by [signal(9)](/signal/9.md). Signals can be sent to processes or process groups using the functions described by [psignal(9)](/psignal/9.md). ### Security See the overview in [security(7)](/security/7.md). The basic structure for user credentials is *struct* *ucred*, managed by the [ucred(9)](/ucred/9.md) API. Thread credentials are verified using [priv(9)](/priv/9.md) to allow or deny certain privileged actions. Policies influenced by *kern.securelevel* must use the [securelevel\_gt(9)](/securelevel_gt/9.md) or [securelevel\_ge(9)](/securelevel_ge/9.md) functions. The Mandatory Access Control (MAC) framework provides a wide set of hooks, supporting dynamically-registered security modules; see [mac(9)](/mac/9.md). Cryptographic services are provided by the OpenCrypto framework. This API provides an interface for both consumers and crypto drivers; see [crypto(9)](/crypto/9.md). For information on random number generation, see [random(9)](/random/9.md) and [prng(9)](/prng/9.md). ### Kernel Modules The interfaces for declaring loadable kernel modules are described by [module(9)](/module/9.md). ### Interrupts [intr\_event(9)](/intr_event/9.md) describes the machine-independent portion of the interrupt framework that supports registration and execution of interrupt handlers. Software interrupts are provided by [swi(9)](/swi/9.md). Device drivers register their interrupt handlers using the [bus\_setup\_intr(9)](/bus_setup_intr/9.md) function. ### Testing and Debugging Tools A kernel test framework: [kern\_testfrwk(9)](/kern_testfrwk/9.md) A facility for defining configurable fail points is described by [fail(9)](/fail/9.md). Commands for the [ddb(4)](/ddb/4.md) kernel debugger are defined with the [DB\_COMMAND(9)](/DB_COMMAND/9.md) family of macros. The [ktr(4)](/ktr/4.md) tracing facility adds static tracepoints to many areas of the kernel. These tracepoints are defined using the macros described by [ktr(9)](/ktr/9.md). Static probes for DTrace are defined using the [SDT(9)](/SDT/9.md) macros. Stack traces can be captured and printed with the [stack(9)](/stack/9.md) API. Kernel sanitizers can perform additional compiler-assisted checks against memory use/access. These runtimes are capable of detecting difficult-to-identify classes of bugs, at the cost of a large overhead. The Kernel Address Sanitizer [KASAN(9)](/KASAN/9.md) and Kernel Memory Sanitizer [KMSAN(9)](/KMSAN/9.md) are supported. The [LOCK\_PROFILING(9)](/LOCK_PROFILING/9.md) kernel config option enables extra code to assist with profiling and/or debugging lock performance. ### Driver Tools Defined functions/APIs for specific types of devices. - [iflib(9)](/iflib/9.md) Programming interface for [iflib(4)](/iflib/4.md) based network drivers. - [pci(9)](/pci/9.md) Peripheral Component Interconnect (PCI) and PCI Express (PCIe) programming API. - [pwmbus(9)](/pwmbus/9.md) Pulse-Width Modulation (PWM) bus interface methods. - [usbdi(9)](/usbdi/9.md) Universal Serial Bus programming interface. - [superio(9)](/superio/9.md) Functions for Super I/O controller devices. ### Miscellaneous Dynamic per-CPU variables: [dpcpu(9)](/dpcpu/9.md). CPU bitmap management: [cpuset(9)](/cpuset/9.md). Kernel environment management: [getenv(9)](/getenv/9.md). Contexts for CPU floating-point registers are managed by the [fpu\_kern(9)](/fpu_kern/9.md) facility. For details on the shutdown/reboot procedure and available shutdown hooks, see [reboot(9)](/reboot/9.md). A facility for asynchronous logging to files from within the kernel is provided by [alq(9)](/alq/9.md). The [osd(9)](/osd/9.md) framework provides a mechanism to dynamically extend core structures in a way that preserves KBI. See the [hhook(9)](/hhook/9.md) and [khelp(9)](/khelp/9.md) APIs for information on how this is used. The kernel object implementation is described by [kobj(9)](/kobj/9.md). ## SEE ALSO [man(1)](/man/1.md), [style(9)](/style/9.md) *The FreeBSD Architecture Handbook*, https://docs.freebsd.org/en/books/arch-handbook/.