kernel-api.tmpl 13 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="LinuxKernelAPI">
 <bookinfo>
  <title>The Linux Kernel API</title>
  
  <legalnotice>
   <para>
     This documentation is free software; you can redistribute
     it and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
   </para>
      
   <para>
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     See the GNU General Public License for more details.
   </para>
      
   <para>
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
     MA 02111-1307 USA
   </para>
      
   <para>
     For more details see the file COPYING in the source
     distribution of Linux.
   </para>
  </legalnotice>
 </bookinfo>

<toc></toc>

  <chapter id="Basics">
     <title>Driver Basics</title>
     <sect1><title>Driver Entry and Exit points</title>
!Iinclude/linux/init.h
     </sect1>

     <sect1><title>Atomic and pointer manipulation</title>
!Iinclude/asm-i386/atomic.h
!Iinclude/asm-i386/unaligned.h
     </sect1>

     <sect1><title>Delaying, scheduling, and timer routines</title>
53 54 55
!Iinclude/linux/sched.h
!Ekernel/sched.c
!Ekernel/timer.c
Linus Torvalds's avatar
Linus Torvalds committed
56
     </sect1>
57 58 59 60 61 62 63 64 65 66 67 68 69 70
     <sect1><title>Internal Functions</title>
!Ikernel/exit.c
!Ikernel/signal.c
     </sect1>

     <sect1><title>Kernel objects manipulation</title>
<!--
X!Iinclude/linux/kobject.h
-->
!Elib/kobject.c
     </sect1>

     <sect1><title>Kernel utility functions</title>
!Iinclude/linux/kernel.h
71
!Ekernel/printk.c
72 73 74 75 76
!Ekernel/panic.c
!Ekernel/sys.c
!Ekernel/rcupdate.c
     </sect1>

Linus Torvalds's avatar
Linus Torvalds committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
  </chapter>

  <chapter id="adt">
     <title>Data Types</title>
     <sect1><title>Doubly Linked Lists</title>
!Iinclude/linux/list.h
     </sect1>
  </chapter>

  <chapter id="libc">
     <title>Basic C Library Functions</title>

     <para>
       When writing drivers, you cannot in general use routines which are
       from the C Library.  Some of the functions have been found generally
       useful and they are listed below.  The behaviour of these functions
       may vary slightly from those defined by ANSI, and these deviations
       are noted in the text.
     </para>

     <sect1><title>String Conversions</title>
!Ilib/vsprintf.c
!Elib/vsprintf.c
     </sect1>
     <sect1><title>String Manipulation</title>
102 103 104
<!-- All functions are exported at now
X!Ilib/string.c
 -->
Linus Torvalds's avatar
Linus Torvalds committed
105 106 107 108 109 110 111 112 113 114 115 116 117 118
!Elib/string.c
     </sect1>
     <sect1><title>Bit Operations</title>
!Iinclude/asm-i386/bitops.h
     </sect1>
  </chapter>

  <chapter id="mm">
     <title>Memory Management in Linux</title>
     <sect1><title>The Slab Cache</title>
!Emm/slab.c
     </sect1>
     <sect1><title>User Space Memory Access</title>
!Iinclude/asm-i386/uaccess.h
119
!Earch/i386/lib/usercopy.c
Linus Torvalds's avatar
Linus Torvalds committed
120
     </sect1>
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
     <sect1><title>More Memory Management Functions</title>
!Iinclude/linux/rmap.h
!Emm/readahead.c
!Emm/filemap.c
!Emm/memory.c
!Emm/vmalloc.c
!Emm/mempool.c
!Emm/page-writeback.c
!Emm/truncate.c
     </sect1>
  </chapter>


  <chapter id="ipc">
     <title>Kernel IPC facilities</title>

     <sect1><title>IPC utilities</title>
!Iipc/util.c
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
  </chapter>

  <chapter id="kfifo">
     <title>FIFO Buffer</title>
     <sect1><title>kfifo interface</title>
!Iinclude/linux/kfifo.h
!Ekernel/kfifo.c
     </sect1>
  </chapter>

  <chapter id="proc">
     <title>The proc filesystem</title>
 
     <sect1><title>sysctl interface</title>
!Ekernel/sysctl.c
     </sect1>
156 157 158 159

     <sect1><title>proc filesystem interface</title>
!Ifs/proc/base.c
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
160 161 162 163 164 165 166 167 168 169 170 171 172
  </chapter>

  <chapter id="debugfs">
     <title>The debugfs filesystem</title>
 
     <sect1><title>debugfs interface</title>
!Efs/debugfs/inode.c
!Efs/debugfs/file.c
     </sect1>
  </chapter>

  <chapter id="vfs">
     <title>The Linux VFS</title>
173 174 175
     <sect1><title>The Filesystem types</title>
!Iinclude/linux/fs.h
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
     <sect1><title>The Directory Cache</title>
!Efs/dcache.c
!Iinclude/linux/dcache.h
     </sect1>
     <sect1><title>Inode Handling</title>
!Efs/inode.c
!Efs/bad_inode.c
     </sect1>
     <sect1><title>Registration and Superblocks</title>
!Efs/super.c
     </sect1>
     <sect1><title>File Locks</title>
!Efs/locks.c
!Ifs/locks.c
     </sect1>
191 192 193 194 195 196 197 198 199 200
     <sect1><title>Other Functions</title>
!Efs/mpage.c
!Efs/namei.c
!Efs/buffer.c
!Efs/bio.c
!Efs/seq_file.c
!Efs/filesystems.c
!Efs/fs-writeback.c
!Efs/block_dev.c
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
201 202 203 204
  </chapter>

  <chapter id="netcore">
     <title>Linux Networking</title>
205 206 207
     <sect1><title>Networking Base Types</title>
!Iinclude/linux/net.h
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
208 209
     <sect1><title>Socket Buffer Functions</title>
!Iinclude/linux/skbuff.h
210 211
!Iinclude/net/sock.h
!Enet/socket.c
Linus Torvalds's avatar
Linus Torvalds committed
212
!Enet/core/skbuff.c
213 214 215
!Enet/core/sock.c
!Enet/core/datagram.c
!Enet/core/stream.c
Linus Torvalds's avatar
Linus Torvalds committed
216 217 218 219 220 221 222 223 224
     </sect1>
     <sect1><title>Socket Filter</title>
!Enet/core/filter.c
     </sect1>
     <sect1><title>Generic Network Statistics</title>
!Iinclude/linux/gen_stats.h
!Enet/core/gen_stats.c
!Enet/core/gen_estimator.c
     </sect1>
225 226 227 228 229 230 231 232
     <sect1><title>SUN RPC subsystem</title>
<!-- The !D functionality is not perfect, garbage has to be protected by comments
!Dnet/sunrpc/sunrpc_syms.c
-->
!Enet/sunrpc/xdr.c
!Enet/sunrpc/svcsock.c
!Enet/sunrpc/sched.c
     </sect1>
Linus Torvalds's avatar
Linus Torvalds committed
233 234 235 236 237 238
  </chapter>

  <chapter id="netdev">
     <title>Network device support</title>
     <sect1><title>Driver Support</title>
!Enet/core/dev.c
239 240 241
!Enet/ethernet/eth.c
!Einclude/linux/etherdevice.h
!Enet/core/wireless.c
Linus Torvalds's avatar
Linus Torvalds committed
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
     </sect1>
     <sect1><title>Synchronous PPP</title>
!Edrivers/net/wan/syncppp.c
     </sect1>
  </chapter>

  <chapter id="modload">
     <title>Module Support</title>
     <sect1><title>Module Loading</title>
!Ekernel/kmod.c
     </sect1>
     <sect1><title>Inter Module support</title>
        <para>
           Refer to the file kernel/module.c for more information.
        </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Ekernel/module.c
-->
     </sect1>
  </chapter>

  <chapter id="hardware">
     <title>Hardware Interfaces</title>
     <sect1><title>Interrupt Handling</title>
266
!Ekernel/irq/manage.c
Linus Torvalds's avatar
Linus Torvalds committed
267 268
     </sect1>

269 270 271 272
     <sect1><title>Resources Management</title>
!Ekernel/resource.c
     </sect1>

Linus Torvalds's avatar
Linus Torvalds committed
273 274 275 276 277
     <sect1><title>MTRR Handling</title>
!Earch/i386/kernel/cpu/mtrr/main.c
     </sect1>
     <sect1><title>PCI Support Library</title>
!Edrivers/pci/pci.c
278 279 280 281 282 283 284 285
!Edrivers/pci/pci-driver.c
!Edrivers/pci/remove.c
!Edrivers/pci/pci-acpi.c
<!-- kerneldoc does not understand to __devinit
X!Edrivers/pci/search.c
 -->
!Edrivers/pci/msi.c
!Edrivers/pci/bus.c
286 287 288
<!-- FIXME: Removed for now since no structured comments in source
X!Edrivers/pci/hotplug.c
-->
289 290
!Edrivers/pci/probe.c
!Edrivers/pci/rom.c
Linus Torvalds's avatar
Linus Torvalds committed
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
     </sect1>
     <sect1><title>PCI Hotplug Support Library</title>
!Edrivers/pci/hotplug/pci_hotplug_core.c
     </sect1>
     <sect1><title>MCA Architecture</title>
	<sect2><title>MCA Device Functions</title>
           <para>
              Refer to the file arch/i386/kernel/mca.c for more information.
           </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Earch/i386/kernel/mca.c
-->
	</sect2>
	<sect2><title>MCA Bus DMA</title>
!Iinclude/asm-i386/mca_dma.h
	</sect2>
     </sect1>
  </chapter>

  <chapter id="devfs">
     <title>The Device File System</title>
!Efs/devfs/base.c
  </chapter>

315 316 317 318 319 320 321 322
  <chapter id="sysfs">
     <title>The Filesystem for Exporting Kernel Objects</title>
!Efs/sysfs/file.c
!Efs/sysfs/dir.c
!Efs/sysfs/symlink.c
!Efs/sysfs/bin.c
  </chapter>

Linus Torvalds's avatar
Linus Torvalds committed
323 324 325 326 327 328 329 330 331 332
  <chapter id="security">
     <title>Security Framework</title>
!Esecurity/security.c
  </chapter>

  <chapter id="pmfuncs">
     <title>Power Management</title>
!Ekernel/power/pm.c
  </chapter>

333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386
  <chapter id="devdrivers">
     <title>Device drivers infrastructure</title>
     <sect1><title>Device Drivers Base</title>
<!--
X!Iinclude/linux/device.h
-->
!Edrivers/base/driver.c
!Edrivers/base/core.c
!Edrivers/base/firmware_class.c
!Edrivers/base/transport_class.c
!Edrivers/base/dmapool.c
<!-- Cannot be included, because
     attribute_container_add_class_device_adapter
 and attribute_container_classdev_to_container
     exceed allowed 44 characters maximum
X!Edrivers/base/attribute_container.c
-->
!Edrivers/base/sys.c
<!--
X!Edrivers/base/interface.c
-->
!Edrivers/base/platform.c
!Edrivers/base/bus.c
     </sect1>
     <sect1><title>Device Drivers Power Management</title>
!Edrivers/base/power/main.c
!Edrivers/base/power/resume.c
!Edrivers/base/power/suspend.c
     </sect1>
     <sect1><title>Device Drivers ACPI Support</title>
<!-- Internal functions only
X!Edrivers/acpi/sleep/main.c
X!Edrivers/acpi/sleep/wakeup.c
X!Edrivers/acpi/motherboard.c
X!Edrivers/acpi/bus.c
-->
!Edrivers/acpi/scan.c
<!-- No correct structured comments
X!Edrivers/acpi/pci_bind.c
-->
     </sect1>
     <sect1><title>Device drivers PnP support</title>
!Edrivers/pnp/core.c
<!-- No correct structured comments
X!Edrivers/pnp/system.c
 -->
!Edrivers/pnp/card.c
!Edrivers/pnp/driver.c
!Edrivers/pnp/manager.c
!Edrivers/pnp/support.c
     </sect1>
  </chapter>


Linus Torvalds's avatar
Linus Torvalds committed
387 388
  <chapter id="blkdev">
     <title>Block Devices</title>
389
!Eblock/ll_rw_blk.c
Linus Torvalds's avatar
Linus Torvalds committed
390 391 392 393 394 395 396 397 398 399 400 401 402 403
  </chapter>

  <chapter id="miscdev">
     <title>Miscellaneous Devices</title>
!Edrivers/char/misc.c
  </chapter>

  <chapter id="viddev">
     <title>Video4Linux</title>
!Edrivers/media/video/videodev.c
  </chapter>

  <chapter id="snddev">
     <title>Sound Devices</title>
404
!Iinclude/sound/core.h
Linus Torvalds's avatar
Linus Torvalds committed
405
!Esound/sound_core.c
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420
!Iinclude/sound/pcm.h
!Esound/core/pcm.c
!Esound/core/device.c
!Esound/core/info.c
!Esound/core/rawmidi.c
!Esound/core/sound.c
!Esound/core/memory.c
!Esound/core/pcm_memory.c
!Esound/core/init.c
!Esound/core/isadma.c
!Esound/core/control.c
!Esound/core/pcm_lib.c
!Esound/core/hwdep.c
!Esound/core/pcm_native.c
!Esound/core/memalloc.c
Linus Torvalds's avatar
Linus Torvalds committed
421 422 423 424 425 426 427
<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
  </chapter>

  <chapter id="uart16x50">
     <title>16x50 UART Driver</title>
428
!Iinclude/linux/serial_core.h
Linus Torvalds's avatar
Linus Torvalds committed
429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
!Edrivers/serial/serial_core.c
!Edrivers/serial/8250.c
  </chapter>

  <chapter id="z85230">
     <title>Z85230 Support Library</title>
!Edrivers/net/wan/z85230.c
  </chapter>

  <chapter id="fbdev">
     <title>Frame Buffer Library</title>

     <para>
       The frame buffer drivers depend heavily on four data structures.  
       These structures are declared in include/linux/fb.h.  They are 
       fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. 
       The last three can be made available to and from userland. 
     </para>

     <para>
       fb_info defines the current state of a particular video card. 
       Inside fb_info, there exists a fb_ops structure which is a 
       collection of needed functions to make fbdev and fbcon work.
       fb_info is only visible to the kernel.
     </para>

     <para>
       fb_var_screeninfo is used to describe the features of a video card 
       that are user defined.  With fb_var_screeninfo, things such as
       depth and the resolution may be defined.
     </para>

     <para>
       The next structure is fb_fix_screeninfo. This defines the 
       properties of a card that are created when a mode is set and can't 
       be changed otherwise.  A good example of this is the start of the 
       frame buffer memory.  This "locks" the address of the frame buffer
       memory, so that it cannot be changed or moved.
     </para>

     <para>
       The last structure is fb_monospecs. In the old API, there was 
       little importance for fb_monospecs. This allowed for forbidden things 
       such as setting a mode of 800x600 on a fix frequency monitor. With 
       the new API, fb_monospecs prevents such things, and if used 
       correctly, can prevent a monitor from being cooked.  fb_monospecs
       will not be useful until kernels 2.5.x.
     </para>

     <sect1><title>Frame Buffer Memory</title>
!Edrivers/video/fbmem.c
     </sect1>
481
<!--
Linus Torvalds's avatar
Linus Torvalds committed
482
     <sect1><title>Frame Buffer Console</title>
483
X!Edrivers/video/console/fbcon.c
Linus Torvalds's avatar
Linus Torvalds committed
484
     </sect1>
485
-->
Linus Torvalds's avatar
Linus Torvalds committed
486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
     <sect1><title>Frame Buffer Colormap</title>
!Edrivers/video/fbcmap.c
     </sect1>
<!-- FIXME:
  drivers/video/fbgen.c has no docs, which stuffs up the sgml.  Comment
  out until somebody adds docs.  KAO
     <sect1><title>Frame Buffer Generic Functions</title>
X!Idrivers/video/fbgen.c
     </sect1>
KAO -->
     <sect1><title>Frame Buffer Video Mode Database</title>
!Idrivers/video/modedb.c
!Edrivers/video/modedb.c
     </sect1>
     <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
501
!Edrivers/video/macmodes.c
Linus Torvalds's avatar
Linus Torvalds committed
502 503 504 505 506 507 508 509 510 511 512
     </sect1>
     <sect1><title>Frame Buffer Fonts</title>
        <para>
           Refer to the file drivers/video/console/fonts.c for more information.
        </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Idrivers/video/console/fonts.c
-->
     </sect1>
  </chapter>
</book>