diff options
Diffstat (limited to 'static/freebsd/man9/intro.9 3.html')
| -rw-r--r-- | static/freebsd/man9/intro.9 3.html | 387 |
1 files changed, 0 insertions, 387 deletions
diff --git a/static/freebsd/man9/intro.9 3.html b/static/freebsd/man9/intro.9 3.html deleted file mode 100644 index 9c218a7a..00000000 --- a/static/freebsd/man9/intro.9 3.html +++ /dev/null @@ -1,387 +0,0 @@ -<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> — - <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 "hold count" 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> |