share/man/man9/intro.9

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