path: root/static/freebsd/man9/intro.9 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">INTRO(9)</td>
    <td class="head-vol">Kernel Developer's Manual</td>
    <td class="head-rtitle">INTRO(9)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">intro</code> &#x2014;
    <span class="Nd">introduction to kernel programming interfaces</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">Welcome to the <span class="Ux">FreeBSD</span> kernel
    documentation. Outside the source code itself, this set of
    <a class="Xr">man(1)</a> 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.</p>
<p class="Pp">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.</p>
<p class="Pp">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.</p>
<p class="Pp">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.</p>
<p class="Pp"><a class="Xr">man(1)</a> pages in this section most frequently
    describe functions, but may also describe types, global variables, macros,
    or high-level concepts.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CODING_GUIDELINES"><a class="permalink" href="#CODING_GUIDELINES">CODING
  GUIDELINES</a></h1>
<p class="Pp">Code written for the <span class="Ux">FreeBSD</span> kernel is
    expected to conform to the established style and coding conventions. Please
    see <a class="Xr">style(9)</a> for a detailed set of rules and
  guidelines.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="OVERVIEW"><a class="permalink" href="#OVERVIEW">OVERVIEW</a></h1>
<p class="Pp">Below is presented various subsystems.</p>
<section class="Ss">
<h2 class="Ss" id="Data_Structures"><a class="permalink" href="#Data_Structures">Data
  Structures</a></h2>
<p class="Pp">There are implementations for many well-known data structures
    available in the kernel.</p>
<dl class="Bl-tag">
  <dt><a class="Xr">bitstring(3)</a></dt>
  <dd>Simple bitmap implementation.</dd>
  <dt><a class="Xr">counter(9)</a></dt>
  <dd>An SMP-safe general-purpose counter implementation.</dd>
  <dt><a class="Xr">hash(9)</a></dt>
  <dd>Hash map implementation.</dd>
  <dt><a class="Xr">nv(9)</a></dt>
  <dd>Name/value pairs.</dd>
  <dt><a class="Xr">queue(3)</a></dt>
  <dd>Singly-linked and doubly-linked lists, and queues.</dd>
  <dt><a class="Xr">refcount(9)</a></dt>
  <dd>An SMP-safe implementation of reference counts.</dd>
  <dt><a class="Xr">sbuf(9)</a></dt>
  <dd>Dynamic string composition.</dd>
  <dt><a class="Xr">sglist(9)</a></dt>
  <dd>A scatter/gather list implementation.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Utility_Functions"><a class="permalink" href="#Utility_Functions">Utility
  Functions</a></h2>
<p class="Pp">Functions or facilities of general usefulness or convenience. See
    also the <a class="Sx" href="#Testing_and_Debugging_Tools">Testing and
    Debugging Tools</a> or <a class="Sx" href="#Miscellaneous">Miscellaneous</a>
    sub-sections below.</p>
<p class="Pp">Formatted output and logging functions are described by
    <a class="Xr">printf(9)</a>.</p>
<p class="Pp">Endian-swapping functions: <a class="Xr">byteorder(9)</a>.</p>
<p class="Pp">Data output in hexadecimal format:
  <a class="Xr">hexdump(9)</a>.</p>
<p class="Pp">A rich set of macros for declaring <a class="Xr">sysctl(8)</a>
    variables and functions is described by <a class="Xr">sysctl(9)</a>.</p>
<p class="Pp" id="_Static_assert">Non-recoverable errors in the kernel should
    trigger a <a class="Xr">panic(9)</a>. Run-time assertions can be verified
    using the <a class="Xr">KASSERT(9)</a> macros. Compile-time assertions
    should use
    <a class="permalink" href="#_Static_assert"><code class="Fn">_Static_assert</code></a>().</p>
<p class="Pp">The SYSINIT framework provides macros for declaring functions that
    will be executed during start-up and shutdown; see
    <a class="Xr">SYSINIT(9)</a>.</p>
<p class="Pp">Deprecation messages may be emitted with
    <a class="Xr">gone_in(9)</a>.</p>
<p class="Pp">A unit number facility is provided by
  <a class="Xr">unr(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Synchronization_Primitives"><a class="permalink" href="#Synchronization_Primitives">Synchronization
  Primitives</a></h2>
<p class="Pp">The <a class="Xr">locking(9)</a> man page gives an overview of the
    various types of locks available in the kernel and advice on their
  usage.</p>
<p class="Pp">Atomic primitives are described by
  <a class="Xr">atomic(9)</a>.</p>
<p class="Pp">The <a class="Xr">epoch(9)</a> and <a class="Xr">smr(9)</a>
    facilities are used to create lock-free data structures. There is also
    <a class="Xr">seqc(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Memory_Management"><a class="permalink" href="#Memory_Management">Memory
  Management</a></h2>
<p class="Pp">Dynamic memory allocations inside the kernel are generally done
    using <a class="Xr">malloc(9)</a>. Frequently allocated objects may prefer
    to use <a class="Xr">uma(9)</a>.</p>
<p class="Pp">Much of the virtual memory system operates on
    <var class="Vt">vm_page_t</var> structures. The following functions are
    documented:</p>
<div class="Bd Pp Bd-indent"><a class="Xr">vm_page_advise(9)</a>,
  <a class="Xr">vm_page_aflag(9)</a>, <a class="Xr">vm_page_alloc(9)</a>,
  <a class="Xr">vm_page_bits(9)</a>, <a class="Xr">vm_page_busy(9)</a>,
  <a class="Xr">vm_page_deactivate(9)</a>, <a class="Xr">vm_page_free(9)</a>,
  <a class="Xr">vm_page_grab(9)</a>, <a class="Xr">vm_page_insert(9)</a>,
  <a class="Xr">vm_page_lookup(9)</a>, <a class="Xr">vm_page_rename(9)</a>,
  <a class="Xr">vm_page_sbusy(9)</a>, <a class="Xr">vm_page_wire(9)</a></div>
<p class="Pp">Virtual address space maps are managed with the
    <a class="Xr">vm_map(9)</a> API.</p>
<p class="Pp">The machine-dependent portion of the virtual memory stack is the
    <a class="Xr">pmap(9)</a> module.</p>
<p class="Pp">Allocation policies for NUMA memory domains are managed with the
    <a class="Xr">domainset(9)</a> API.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="File_Systems"><a class="permalink" href="#File_Systems">File
  Systems</a></h2>
<p class="Pp">The kernel interface for file systems is <a class="Xr">VFS(9)</a>.
    File system implementations register themselves with
    <a class="Xr">vfsconf(9)</a>.</p>
<p class="Pp">The <a class="Xr">vnode(9)</a> is the abstract and
    filesystem-independent representation of a file, directory, or other
    file-like entity within the kernel.</p>
<p class="Pp">The implementation of access control lists for filesystems is
    described by <a class="Xr">acl(9)</a>. Also
  <a class="Xr">vaccess(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="I/O_and_Storage"><a class="permalink" href="#I/O_and_Storage">I/O
  and Storage</a></h2>
<p class="Pp">The GEOM framework represents I/O requests using the
    <a class="Xr">bio(9)</a> structure.</p>
<p class="Pp">Disk drivers connect themselves to GEOM using the
    <a class="Xr">disk(9)</a> API.</p>
<p class="Pp">The <a class="Xr">devstat(9)</a> facility provides an interface
    for recording device statistics in disk drivers.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Networking"><a class="permalink" href="#Networking">Networking</a></h2>
<p class="Pp">Much of the networking stack uses the <a class="Xr">mbuf(9)</a>, a
    flexible memory management unit commonly used to store network packets.</p>
<p class="Pp">Network interfaces are implemented using the
    <a class="Xr">ifnet(9)</a> API, which has functions for drivers and
    consumers.</p>
<p class="Pp">A framework for managing packet output queues is described by
    <a class="Xr">altq(9)</a>.</p>
<p class="Pp">To receive incoming packets, network protocols register themselves
    with <a class="Xr">netisr(9)</a>.</p>
<p class="Pp">Virtualization of the network stack is provided by
    <a class="Xr">VNET(9)</a>.</p>
<p class="Pp">The front-end for interfacing with network sockets from within the
    kernel is described by <a class="Xr">socket(9)</a>. The back-end interface
    for socket implementations is <a class="Xr">domain(9)</a>.</p>
<p class="Pp">The low-level packet filter interface is described by
    <a class="Xr">pfil(9)</a>.</p>
<p class="Pp">The <a class="Xr">bpf(9)</a> interface provides a mechanism to
    redirect packets to userspace.</p>
<p class="Pp">The subsystem for IEEE 802.11 wireless networking is described by
    <a class="Xr">ieee80211(9)</a>.</p>
<p class="Pp">A framework for modular TCP implementations is described by
    <a class="Xr">tcp_functions(9)</a>.</p>
<p class="Pp">A framework for modular congestion control algorithms is described
    by <a class="Xr">mod_cc(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Device_Drivers"><a class="permalink" href="#Device_Drivers">Device
  Drivers</a></h2>
<p class="Pp">Consult the <a class="Xr">device(9)</a> and
    <a class="Xr">driver(9)</a> pages first.</p>
<p class="Pp">Most drivers act as devices, and provide a set of methods
    implementing the device interface. This includes methods such as
    <a class="Xr">DEVICE_PROBE(9)</a>, <a class="Xr">DEVICE_ATTACH(9)</a>, and
    <a class="Xr">DEVICE_DETACH(9)</a>.</p>
<p class="Pp">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 <a class="Xr">BUS_ADD_CHILD(9)</a>,
    <a class="Xr">BUS_READ_IVAR(9)</a>, or <a class="Xr">BUS_RESCAN(9)</a>.</p>
<p class="Pp">Buses often perform resource accounting on behalf of their
    children. For this there is the <a class="Xr">rman(9)</a> API.</p>
<p class="Pp">Drivers can request and manage their resources (e.g. memory-space
    or IRQ number) from their parent using the following sets of functions:</p>
<div class="Bd Pp Bd-indent"><a class="Xr">bus_alloc_resource(9)</a>,
  <a class="Xr">bus_adjust_resource(9)</a>,
  <a class="Xr">bus_get_resource(9)</a>, <a class="Xr">bus_map_resource(9)</a>,
  <a class="Xr">bus_release_resource(9)</a>,
  <a class="Xr">bus_set_resource(9)</a></div>
<p class="Pp">Direct Memory Access (DMA) is handled using the
    <a class="Xr">busdma(9)</a> framework.</p>
<p class="Pp">Functions for accessing bus space (i.e. read/write) are provided
    by <a class="Xr">bus_space(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Clocks_and_Timekeeping"><a class="permalink" href="#Clocks_and_Timekeeping">Clocks
  and Timekeeping</a></h2>
<p class="Pp">The kernel clock frequency and overall system time model is
    described by <a class="Xr">hz(9)</a>.</p>
<p class="Pp">A few global time variables, such as system up-time, are described
    by <a class="Xr">time(9)</a>.</p>
<p class="Pp">Raw CPU cycles are provided by
    <a class="Xr">get_cyclecount(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Userspace_Memory_Access"><a class="permalink" href="#Userspace_Memory_Access">Userspace
  Memory Access</a></h2>
<p class="Pp">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.</p>
<p class="Pp">Most device drivers use the <a class="Xr">uiomove(9)</a> set of
    routines.</p>
<p class="Pp">Simpler primitives for reading or writing smaller chunks of memory
    are described by <a class="Xr">casuword(9)</a>, <a class="Xr">copy(9)</a>,
    <a class="Xr">fetch(9)</a>, and <a class="Xr">store(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Kernel_Threads,_Tasks,_and_Callbacks"><a class="permalink" href="#Kernel_Threads,_Tasks,_and_Callbacks">Kernel
  Threads, Tasks, and Callbacks</a></h2>
<p class="Pp">Kernel threads and processes are created using the
    <a class="Xr">kthread(9)</a> and <a class="Xr">kproc(9)</a> interfaces,
    respectively.</p>
<p class="Pp">Where dedicated kernel threads are too heavyweight, there is also
    the <a class="Xr">taskqueue(9)</a> interface.</p>
<p class="Pp">For low-latency callback handling, the
    <a class="Xr">callout(9)</a> framework should be used.</p>
<p class="Pp">Dynamic handlers for pre-defined event hooks are registered and
    invoked using the <a class="Xr">EVENTHANDLER(9)</a> API.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Thread_Switching_and_Scheduling"><a class="permalink" href="#Thread_Switching_and_Scheduling">Thread
  Switching and Scheduling</a></h2>
<p class="Pp">The machine-independent interface to a context switch is
    <a class="Xr">mi_switch(9)</a>.</p>
<p class="Pp">To prevent preemption, use a <a class="Xr">critical(9)</a>
    section.</p>
<p class="Pp">To voluntarily yield the processor, use
    <a class="Xr">kern_yield(9)</a>.</p>
<p class="Pp">The various functions which will deliberately put a thread to
    sleep are described by <a class="Xr">sleep(9)</a>. Sleeping threads are
    removed from the scheduler and placed on a
  <a class="Xr">sleepqueue(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Processes_and_Signals"><a class="permalink" href="#Processes_and_Signals">Processes
  and Signals</a></h2>
<p class="Pp">To locate a process or process group by its identifier, use
    <a class="Xr">pfind(9)</a> and <a class="Xr">pgfind(9)</a>. Alternatively,
    the <a class="Xr">pget(9)</a> function provides additional search
    specificity.</p>
<p class="Pp">The &quot;hold count&quot; of a process can be manipulated with
    <a class="Xr">PHOLD(9)</a>.</p>
<p class="Pp">The kernel interface for signals is described by
    <a class="Xr">signal(9)</a>.</p>
<p class="Pp">Signals can be sent to processes or process groups using the
    functions described by <a class="Xr">psignal(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Security"><a class="permalink" href="#Security">Security</a></h2>
<p class="Pp">See the overview in <a class="Xr">security(7)</a>.</p>
<p class="Pp">The basic structure for user credentials is <var class="Vt">struct
    ucred</var>, managed by the <a class="Xr">ucred(9)</a> API. Thread
    credentials are verified using <a class="Xr">priv(9)</a> to allow or deny
    certain privileged actions.</p>
<p class="Pp">Policies influenced by <var class="Va">kern.securelevel</var> must
    use the <a class="Xr">securelevel_gt(9)</a> or
    <a class="Xr">securelevel_ge(9)</a> functions.</p>
<p class="Pp">The Mandatory Access Control (MAC) framework provides a wide set
    of hooks, supporting dynamically-registered security modules; see
    <a class="Xr">mac(9)</a>.</p>
<p class="Pp">Cryptographic services are provided by the OpenCrypto framework.
    This API provides an interface for both consumers and crypto drivers; see
    <a class="Xr">crypto(9)</a>.</p>
<p class="Pp">For information on random number generation, see
    <a class="Xr">random(9)</a> and <a class="Xr">prng(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Kernel_Modules"><a class="permalink" href="#Kernel_Modules">Kernel
  Modules</a></h2>
<p class="Pp">The interfaces for declaring loadable kernel modules are described
    by <a class="Xr">module(9)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Interrupts"><a class="permalink" href="#Interrupts">Interrupts</a></h2>
<p class="Pp"><a class="Xr">intr_event(9)</a> describes the machine-independent
    portion of the interrupt framework that supports registration and execution
    of interrupt handlers.</p>
<p class="Pp">Software interrupts are provided by <a class="Xr">swi(9)</a>.</p>
<p class="Pp">Device drivers register their interrupt handlers using the
    <a class="Xr">bus_setup_intr(9)</a> function.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Testing_and_Debugging_Tools"><a class="permalink" href="#Testing_and_Debugging_Tools">Testing
  and Debugging Tools</a></h2>
<p class="Pp">A kernel test framework: <a class="Xr">kern_testfrwk(9)</a></p>
<p class="Pp">A facility for defining configurable fail points is described by
    <a class="Xr">fail(9)</a>.</p>
<p class="Pp">Commands for the <a class="Xr">ddb(4)</a> kernel debugger are
    defined with the <a class="Xr">DB_COMMAND(9)</a> family of macros.</p>
<p class="Pp">The <a class="Xr">ktr(4)</a> tracing facility adds static
    tracepoints to many areas of the kernel. These tracepoints are defined using
    the macros described by <a class="Xr">ktr(9)</a>.</p>
<p class="Pp">Static probes for DTrace are defined using the
    <a class="Xr">SDT(9)</a> macros.</p>
<p class="Pp">Stack traces can be captured and printed with the
    <a class="Xr">stack(9)</a> API.</p>
<p class="Pp">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 <a class="Xr">KASAN(9)</a> and Kernel Memory
    Sanitizer <a class="Xr">KMSAN(9)</a> are supported.</p>
<p class="Pp">The <a class="Xr">LOCK_PROFILING(9)</a> kernel config option
    enables extra code to assist with profiling and/or debugging lock
    performance.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Driver_Tools"><a class="permalink" href="#Driver_Tools">Driver
  Tools</a></h2>
<p class="Pp">Defined functions/APIs for specific types of devices.</p>
<dl class="Bl-tag">
  <dt><a class="Xr">iflib(9)</a></dt>
  <dd>Programming interface for <a class="Xr">iflib(4)</a> based network
      drivers.</dd>
  <dt><a class="Xr">pci(9)</a></dt>
  <dd>Peripheral Component Interconnect (PCI) and PCI Express (PCIe) programming
      API.</dd>
  <dt><a class="Xr">pwmbus(9)</a></dt>
  <dd>Pulse-Width Modulation (PWM) bus interface methods.</dd>
  <dt><a class="Xr">usbdi(9)</a></dt>
  <dd>Universal Serial Bus programming interface.</dd>
  <dt><a class="Xr">superio(9)</a></dt>
  <dd>Functions for Super I/O controller devices.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Miscellaneous"><a class="permalink" href="#Miscellaneous">Miscellaneous</a></h2>
<p class="Pp">Dynamic per-CPU variables: <a class="Xr">dpcpu(9)</a>.</p>
<p class="Pp">CPU bitmap management: <a class="Xr">cpuset(9)</a>.</p>
<p class="Pp">Kernel environment management: <a class="Xr">getenv(9)</a>.</p>
<p class="Pp">Contexts for CPU floating-point registers are managed by the
    <a class="Xr">fpu_kern(9)</a> facility.</p>
<p class="Pp">For details on the shutdown/reboot procedure and available
    shutdown hooks, see <a class="Xr">reboot(9)</a>.</p>
<p class="Pp">A facility for asynchronous logging to files from within the
    kernel is provided by <a class="Xr">alq(9)</a>.</p>
<p class="Pp">The <a class="Xr">osd(9)</a> framework provides a mechanism to
    dynamically extend core structures in a way that preserves KBI. See the
    <a class="Xr">hhook(9)</a> and <a class="Xr">khelp(9)</a> APIs for
    information on how this is used.</p>
<p class="Pp">The kernel object implementation is described by
    <a class="Xr">kobj(9)</a>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">man(1)</a>, <a class="Xr">style(9)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsT">The FreeBSD Architecture
    Handbook</span>,
    <a class="RsU" href="https://docs.freebsd.org/en/books/arch-handbook/">https://docs.freebsd.org/en/books/arch-handbook/</a>.</cite></p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">January 30, 2024</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>