1.\" $NetBSD: intro.9,v 1.11 2009/05/04 19:42:14 wiz Exp $ 2.\" 3.\" Copyright (c) 1997, 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jeremy Cooper, and Mindaugas Rasiukevicius. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 17, 2007 31.Dt INTRO 9 32.Os 33.Sh NAME 34.Nm intro 35.Nd introduction to kernel internals 36.Sh DESCRIPTION 37This section contains information related to the internal operation of the 38system kernel. 39It describes function interfaces and variables of use to the systems and device 40driver programmer. 41.Pp 42In addition to the normal man page format, the kernel pages include an 43additional section: 44.Bl -tag -width "CODE REFERENCES" 45.It "CODE REFERENCES" 46Contains the pathname(s) of the source file(s) which contain the definition 47and/or source code of the variables or functions being documented. 48.El 49.Sh MEMORY MANAGEMENT 50Machine-dependent swap interface. 51See 52.Xr cpu_swapout 9 . 53.Pp 54Introduction to kernel memory allocators. 55See 56.Xr memoryallocators 9 . 57.Pp 58Machine-dependent portion of the virtual memory system. 59See 60.Xr pmap 9 . 61.Pp 62Virtual memory system external interface. 63See 64.Xr uvm 9 . 65.Sh I/O SUBSYSTEM 66Buffer cache interfaces. 67See 68.Xr buffercache 9 . 69.Pp 70Device buffer queues. 71See 72.Xr bufq 9 . 73.Pp 74Initiate I/O on raw devices. 75See 76.Xr physio 9 . 77.Pp 78I/O descriptor allocation interface. 79See 80.Xr getiobuf 9 . 81.Sh PROCESS CONTROL 82Machine-dependent process exit. 83See 84.Xr cpu_exit 9 . 85.Pp 86Idle CPU while waiting for work. 87See 88.Xr cpu_idle 9 . 89.Pp 90Finish a fork operation. 91See 92.Xr cpu_lwp_fork 9 . 93.Pp 94Switch to another light weight process. 95See 96.Xr mi_switch 9 . 97.Pp 98Current process and processor. 99See 100.Xr curproc 9 . 101.Pp 102Set process uid and gid. 103See 104.Xr do_setresuid 9 . 105.Pp 106New processes and kernel threads. 107See 108.Xr fork1 9 , 109.Xr kthread 9 . 110.Pp 111Context switch notification. 112See 113.Xr cpu_need_resched 9 . 114.Pp 115Process scheduling subsystem. 116See 117.Xr scheduler 9 . 118.Pp 119Software signal facilities. 120See 121.Xr signal 9 . 122.Pp 123Suspend the scheduler. 124See 125.Xr suspendsched 9 . 126.Pp 127Return path to user-mode execution. 128See 129.Xr userret 9 . 130.Sh FILE SYSTEM 131High-level file operations. 132See 133.Xr dofileread 9 . 134.Pp 135Convert an extended attribute namespace identifier to a string and 136vice versa. 137See 138.Xr extattr 9 . 139.Pp 140Operations on file entries. 141See 142.Xr file 9 . 143.Pp 144In-kernel, file-system independent, file-meta data association. 145See 146.Xr fileassoc 9 . 147.Pp 148File descriptor tables and operations. 149See 150.Xr filedesc 9 . 151.Pp 152File descriptor owner handling functions. 153See 154.Xr fsetown 9 . 155.Pp 156File system suspension helper subsystem. 157See 158.Xr fstrans 9 . 159.Pp 160Pathname lookup, cache and management. 161See 162.Xr namei 9 , 163.Xr namecache 9 , 164.Xr pathname 9 . 165.Pp 166Kernel interface to file systems. 167See 168.Xr vfs 9 . 169.Pp 170Kernel representation of a file or directory and vnode attributes. 171See 172.Xr vnode 9 , 173.Xr vattr 9 . 174.Sh NETWORKING 175Kernel interfaces for manipulating output queues on network interfaces. 176See 177.Xr altq 9 . 178.Pp 179Externally visible ARP functions. 180See 181.Xr arp 9 . 182.Pp 183Ethernet and FDDI driver support functions and macros. 184See 185.Xr ethersubr 9 . 186.Pp 187Core 802.11 network stack functions and rate adaptation based on 188received signal strength. 189See 190.Xr ieee80211 9 , 191.Xr rssadapt 9 . 192.Pp 193Compute Internet checksum. 194See 195.Xr in_cksum 9 . 196.Pp 197Look up the IPv4 source address best matching an IPv4 destination. 198See 199.Xr in_getifa 9 . 200.Pp 201Functions and macros for managing memory used by networking code. 202See 203.Xr mbuf 9 . 204.Pp 205Packet filter interface. 206See 207.Xr pfil 9 . 208.Pp 209Route callout functions. 210See 211.Xr rt_timer 9 . 212.Pp 213TCP congestion control API. 214See 215.Xr tcp_congctl 9 . 216.Sh LOCKING AND INTERRUPT CONTROL 217Condition variables. 218See 219.Xr condvar 9 . 220.Pp 221Kernel lock functions. 222See 223.Xr lock 9 . 224.Pp 225Memory barriers. 226See 227.Xr mb 9 . 228.Pp 229Mutual exclusion primitives. 230See 231.Xr mutex 9 . 232.Pp 233Restartable atomic sequences. 234See 235.Xr ras 9 . 236.Pp 237Reader / writer lock primitives. 238See 239.Xr rwlock 9 . 240.Pp 241Machine-independent software interrupt framework. 242See 243.Xr softintr 9 . 244.Pp 245Functions to modify system interrupt priority level. 246See 247.Xr spl 9 . 248.Pp 249Functions ro raise the system priority level. 250See 251.Xr splraiseipl 9 . 252.Sh SECURITY 253Kernel authorization framework. 254See 255.Xr kauth 9 . 256.Pp 257API for cryptographic services in the kernel. 258See 259.Xr opencrypto 9 . 260.Pp 261Security model development guidelines. 262See 263.Xr secmodel 9 . 264.Sh SYSTEM TIME CONTROL 265Execute a function after a specified length of time. 266See 267.Xr callout 9 . 268.Pp 269Microsecond delay. 270See 271.Xr delay 9 . 272.Pp 273Real-time timer. 274See 275.Xr hardclock 9 . 276.Pp 277System clock frequency. 278See 279.Xr hz 9 . 280.Pp 281Initialization of system time and time-of-day clock support. 282See 283.Xr inittodr 9 , 284.Xr todr 9 . 285.Pp 286Check that a timeval value is valid, and correct. 287See 288.Xr itimerfix 9 . 289.Pp 290System time variables. 291See 292.Xr timecounter 9 . 293.Pp 294Realtime system clock. 295See 296.Xr microtime 9 . 297.Pp 298Get the time elapsed since boot. 299See 300.Xr microuptime 9 . 301.Pp 302Convert milliseconds to system clock ticks. 303See 304.Xr mstohz 9 . 305.Pp 306Function to help implement rate-limited actions. 307See 308.Xr ppsratecheck 9 . 309.Pp 310Function to help implement rate-limited actions. 311See 312.Xr ratecheck 9 . 313.Pp 314Set battery-backed clock from system time. 315See 316.Xr resettodr 9 . 317.Pp 318System time variables. 319See 320.Xr time_second 9 . 321.Sh KERNEL AND USER SPACE DATA COPY FUNCTIONS 322Kernel space to/from user space copy functions. 323See 324.Xr copy 9 . 325.Pp 326Store data to user-space. 327See 328.Xr store 9 . 329.Pp 330Fetch data from user-space. 331See 332.Xr fetch 9 . 333.Pp 334Move data described by a struct uio. 335See 336.Xr uiomove 9 . 337.Sh MACHINE DEPENDENT KERNEL FUNCTIONS 338Machine-dependent clock setup interface. 339See 340.Xr cpu_initclocks 9 . 341.Pp 342Machine-dependent process core dump interface. 343See 344.Xr cpu_coredump 9 . 345.Pp 346Machine-dependent kernel core dumps. 347See 348.Xr cpu_dumpconf 9 . 349.Pp 350Unique CPU identification number 351See 352.Xr cpu_number 9 . 353.Pp 354Halt or reboot the system 355See 356.Xr cpu_reboot 9 . 357.Pp 358Machine-dependent root file system setup 359See 360.Xr cpu_rootconf 9 . 361.Pp 362Machine-dependent CPU startup 363See 364.Xr cpu_startup 9 . 365.Pp 366Disk label management routines. 367See 368.Xr disklabel 9 . 369.Sh DEVICE CONFIGURATION 370Autoconfiguration frame-work. 371See 372.Xr autoconf 9 . 373.Pp 374Description of a device driver. 375See 376.Xr driver 9 . 377.Pp 378The autoconfiguration framework ``device definition'' language. 379See 380.Xr config 9 . 381.Pp 382Machine-dependent device autoconfiguration. 383See 384.Xr cpu_configure 9 . 385.Sh MI DEVICE DRIVER API 386Bus and Machine Independent DMA Mapping Interface. 387See 388.Xr bus_dma 9 . 389.Pp 390Bus space manipulation functions. 391See 392.Xr bus_space 9 . 393.Pp 394Generic disk framework. 395See 396.Xr disk 9 . 397.Pp 398Hardware-assisted data mover interface. 399See 400.Xr dmover 9 . 401Generic event counter framework. 402See 403.Xr evcnt 9 . 404.Pp 405Firmware loader API for device drivers. 406See 407.Xr firmload 9 . 408.Pp 409How to implement a new ioctl call to access device drivers. 410See 411.Xr ioctl 9 . 412.Pp 413Extensible line discipline framework. 414See 415.Xr linedisc 9 . 416.Sh CONSOLE DEVICES 417Console magic key sequence management. 418See 419.Xr cnmagic 9 . 420.Pp 421Console access interface. 422See 423.Xr cons 9 . 424.Pp 425Raster display operations. 426See 427.Xr rasops 9 . 428.Pp 429Generic virtual console framework. 430See 431.Xr vcons 9 . 432.Pp 433Machine-independent console support. 434See 435.Xr wscons 9 . 436.Sh DEVICE SPECIFIC IMPLEMENTATION 437Interface between low and high level audio drivers. 438See 439.Xr audio 9 . 440.Pp 441Bluetooth Device/Protocol API. 442See 443.Xr bluetooth 9 . 444.Pp 445Support for CardBus PC-Card devices. 446See 447.Xr cardbus 9 . 448.Pp 449VESA Display Data Channel V2. 450See 451.Xr ddc 9 . 452.Pp 453VESA Extended Display Identification Data. 454See 455.Xr edid 9 . 456.Pp 457Inter IC (I2C) bus. 458See 459.Xr iic 9 . 460.Pp 461Baseboard I/O control ASIC for DEC TURBOchannel systems. 462See 463.Xr ioasic 9 . 464.Pp 465Industry-standard Architecture. 466See 467.Xr isa 9 . 468.Pp 469Introduction to ISA Plug-and-Play support. 470See 471.Xr isapnp 9 . 472.Pp 473MicroChannel Architecture bus. 474See 475.Xr mca 9 . 476.Pp 477PPBUS microseqencer developer's guide. 478See 479.Xr microseq 9 . 480.Pp 481Peripheral Component Interconnect. 482See 483.Xr pci 9 . 484.Pp 485Perform PCI bus configuration. 486See 487.Xr pci_configure_bus 9 . 488.Pp 489PCI bus interrupt manipulation functions. 490See 491.Xr pci_intr 9 . 492.Pp 493PC keyboard port interface. 494See 495.Xr pckbport 9 . 496.Pp 497Support for PCMCIA PC-Card devices. 498See 499.Xr pcmcia 9 . 500.Pp 501User-space interface to ppbus parallel port. 502See 503.Xr ppi 9 . 504.Pp 505Interface between low and high level radio drivers. 506See 507.Xr radio 9 . 508.Pp 509Functions to make a device available for entropy collection. 510See 511.Xr rnd 9 . 512.Pp 513SCSI/ATAPI middle-layer interface. 514See 515.Xr scsipi 9 . 516.Pp 517TURBOchannel bus. 518See 519.Xr tc 9 . 520.Pp 521USB tty support. 522See 523.Xr ucom 9 . 524.Pp 525USB device drivers interface. 526See 527.Xr usbdi 9 . 528.Pp 529Versa Module Euroboard bus. 530See 531.Xr vme 9 . 532.Pp 533Machine-independent IDE/ATAPI driver. 534See 535.Xr wdc 9 . 536.Sh KERNEL EVENT 537Functions to add or remove kernel event filters. 538See 539.Xr kfilter_register 9 . 540.Pp 541Functions to raise kernel event. 542See 543.Xr knote 9 . 544.Pp 545Record and wakeup select requests. 546See 547.Xr selrecord 9 . 548.Pp 549Simple do-it-in-thread-context framework. 550See 551.Xr workqueue 9 . 552.Sh KERNEL HELPER FUNCTIONS 553Kernel expression verification macros. 554See 555.Xr KASSERT 9 . 556.Pp 557Convert a single byte between (unsigned) packed bcd and binary. 558See 559.Xr bcdtobin 9 . 560.Pp 561Bitmask output conversion. 562See 563.Xr snprintb 3 . 564.Pp 565General purpose extent manager. 566See 567.Xr extent 9 . 568.Pp 569Compare integers. 570See 571.Xr imax 9 . 572.Pp 573Kernel formatted output conversion. 574See 575.Xr kprintf 9 . 576.Pp 577Data comparing, moving, copying, setting and cleaning. 578See 579.Xr memcmp 9 , 580.Xr memmove 9 , 581.Xr memcpy 9 , 582.Xr memset 9 , 583.Xr bcmp 9 , 584.Xr bcopy 9 , 585.Xr bzero 9 , 586.Xr kcopy 9 . 587.Pp 588Log a message from the kernel through the /dev/klog device. 589See 590.Xr log 9 . 591.Pp 592Bring down system on fatal error. 593See 594.Xr panic 9 . 595.Sh MISC 596Run all power hooks. 597See 598.Xr dopowerhooks 9 . 599.Pp 600Run all shutdown hooks. 601See 602.Xr doshutdownhooks 9 . 603.Pp 604Kernel internal error numbers. 605See 606.Xr errno 9 . 607.Pp 608Kernel hash functions, hash table construction and destruction. 609See 610.Xr hash 9 , 611.Xr hashinit 9 . 612.Pp 613Format a number into a human readable form. 614See 615.Xr humanize_number 9 . 616.Pp 617Machine-dependent interface to ipkdb. 618See 619.Xr ipkdb 9 . 620.Pp 621Options string management. 622See 623.Xr optstr 9 . 624.Pp 625Performs pattern matching on strings. 626See 627.Xr pmatch 9 . 628.Pp 629Hardware Performance Monitoring Interface. 630See 631.Xr pmc 9 . 632.Pp 633Add or remove a power change hook. 634See 635.Xr powerhook_establish 9 . 636.Pp 637Add or remove a shutdown hook. 638See 639.Xr shutdownhook_establish 9 . 640.Pp 641Non-local jumps. 642See 643.Xr setjmp 9 . 644.Pp 645System variable control interfaces. 646See 647.Xr sysctl 9 . 648.Sh HISTORY 649The 650.Nx 651kernel internals section first appeared in 652.Nx 1.2 . 653