]> git.proxmox.com Git - mirror_ubuntu-zesty-kernel.git/blame - Documentation/DocBook/kernel-api.tmpl
[PATCH] kernel-doc for kernel/dma.c
[mirror_ubuntu-zesty-kernel.git] / Documentation / DocBook / kernel-api.tmpl
CommitLineData
1da177e4
LT
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="LinuxKernelAPI">
6 <bookinfo>
7 <title>The Linux Kernel API</title>
8
9 <legalnotice>
10 <para>
11 This documentation is free software; you can redistribute
12 it and/or modify it under the terms of the GNU General Public
13 License as published by the Free Software Foundation; either
14 version 2 of the License, or (at your option) any later
15 version.
16 </para>
17
18 <para>
19 This program is distributed in the hope that it will be
20 useful, but WITHOUT ANY WARRANTY; without even the implied
21 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
22 See the GNU General Public License for more details.
23 </para>
24
25 <para>
26 You should have received a copy of the GNU General Public
27 License along with this program; if not, write to the Free
28 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
29 MA 02111-1307 USA
30 </para>
31
32 <para>
33 For more details see the file COPYING in the source
34 distribution of Linux.
35 </para>
36 </legalnotice>
37 </bookinfo>
38
39<toc></toc>
40
41 <chapter id="Basics">
42 <title>Driver Basics</title>
43 <sect1><title>Driver Entry and Exit points</title>
44!Iinclude/linux/init.h
45 </sect1>
46
47 <sect1><title>Atomic and pointer manipulation</title>
48!Iinclude/asm-i386/atomic.h
49!Iinclude/asm-i386/unaligned.h
50 </sect1>
51
1da177e4 52 <sect1><title>Delaying, scheduling, and timer routines</title>
4dc3b16b
PP
53!Iinclude/linux/sched.h
54!Ekernel/sched.c
55!Ekernel/timer.c
df78488d
TG
56 </sect1>
57 <sect1><title>High-resolution timers</title>
58!Iinclude/linux/ktime.h
59!Iinclude/linux/hrtimer.h
60!Ekernel/hrtimer.c
0fcb78c2
REB
61 </sect1>
62 <sect1><title>Workqueues and Kevents</title>
63!Ekernel/workqueue.c
1da177e4 64 </sect1>
4dc3b16b
PP
65 <sect1><title>Internal Functions</title>
66!Ikernel/exit.c
67!Ikernel/signal.c
9e37bd30
RD
68!Iinclude/linux/kthread.h
69!Ekernel/kthread.c
4dc3b16b
PP
70 </sect1>
71
72 <sect1><title>Kernel objects manipulation</title>
73<!--
74X!Iinclude/linux/kobject.h
75-->
76!Elib/kobject.c
77 </sect1>
78
79 <sect1><title>Kernel utility functions</title>
80!Iinclude/linux/kernel.h
ddad86c2 81!Ekernel/printk.c
4dc3b16b
PP
82!Ekernel/panic.c
83!Ekernel/sys.c
84!Ekernel/rcupdate.c
85 </sect1>
86
1da177e4
LT
87 </chapter>
88
89 <chapter id="adt">
90 <title>Data Types</title>
91 <sect1><title>Doubly Linked Lists</title>
92!Iinclude/linux/list.h
93 </sect1>
94 </chapter>
95
96 <chapter id="libc">
97 <title>Basic C Library Functions</title>
98
99 <para>
100 When writing drivers, you cannot in general use routines which are
101 from the C Library. Some of the functions have been found generally
102 useful and they are listed below. The behaviour of these functions
103 may vary slightly from those defined by ANSI, and these deviations
104 are noted in the text.
105 </para>
106
107 <sect1><title>String Conversions</title>
108!Ilib/vsprintf.c
109!Elib/vsprintf.c
110 </sect1>
111 <sect1><title>String Manipulation</title>
4dc3b16b
PP
112<!-- All functions are exported at now
113X!Ilib/string.c
114 -->
1da177e4
LT
115!Elib/string.c
116 </sect1>
117 <sect1><title>Bit Operations</title>
118!Iinclude/asm-i386/bitops.h
119 </sect1>
28e83baa
RD
120 </chapter>
121
122 <chapter id="kernel-lib">
123 <title>Basic Kernel Library Functions</title>
124
125 <para>
126 The Linux kernel provides more basic utility functions.
127 </para>
128
6e1907ff
RD
129 <sect1><title>Bitmap Operations</title>
130!Elib/bitmap.c
131!Ilib/bitmap.c
132 </sect1>
28e83baa
RD
133
134 <sect1><title>Command-line Parsing</title>
135!Elib/cmdline.c
136 </sect1>
2f72100c
RD
137
138 <sect1><title>CRC Functions</title>
139!Elib/crc16.c
140!Elib/crc32.c
141!Elib/crc-ccitt.c
142 </sect1>
1da177e4
LT
143 </chapter>
144
145 <chapter id="mm">
146 <title>Memory Management in Linux</title>
147 <sect1><title>The Slab Cache</title>
800590f5 148!Iinclude/linux/slab.h
1da177e4
LT
149!Emm/slab.c
150 </sect1>
151 <sect1><title>User Space Memory Access</title>
152!Iinclude/asm-i386/uaccess.h
8f2709b5 153!Earch/i386/lib/usercopy.c
1da177e4 154 </sect1>
4dc3b16b
PP
155 <sect1><title>More Memory Management Functions</title>
156!Iinclude/linux/rmap.h
157!Emm/readahead.c
158!Emm/filemap.c
159!Emm/memory.c
160!Emm/vmalloc.c
161!Emm/mempool.c
162!Emm/page-writeback.c
163!Emm/truncate.c
164 </sect1>
165 </chapter>
166
167
168 <chapter id="ipc">
169 <title>Kernel IPC facilities</title>
170
171 <sect1><title>IPC utilities</title>
172!Iipc/util.c
173 </sect1>
1da177e4
LT
174 </chapter>
175
176 <chapter id="kfifo">
177 <title>FIFO Buffer</title>
178 <sect1><title>kfifo interface</title>
179!Iinclude/linux/kfifo.h
180!Ekernel/kfifo.c
181 </sect1>
182 </chapter>
183
5b217fa7
RD
184 <chapter id="vfs">
185 <title>The Linux VFS</title>
186 <sect1><title>The Filesystem types</title>
187!Iinclude/linux/fs.h
188 </sect1>
189 <sect1><title>The Directory Cache</title>
190!Efs/dcache.c
191!Iinclude/linux/dcache.h
192 </sect1>
193 <sect1><title>Inode Handling</title>
194!Efs/inode.c
195!Efs/bad_inode.c
196 </sect1>
197 <sect1><title>Registration and Superblocks</title>
198!Efs/super.c
199 </sect1>
200 <sect1><title>File Locks</title>
201!Efs/locks.c
202!Ifs/locks.c
203 </sect1>
204 <sect1><title>Other Functions</title>
205!Efs/mpage.c
206!Efs/namei.c
207!Efs/buffer.c
208!Efs/bio.c
209!Efs/seq_file.c
210!Efs/filesystems.c
211!Efs/fs-writeback.c
212!Efs/block_dev.c
213 </sect1>
214 </chapter>
215
1da177e4
LT
216 <chapter id="proc">
217 <title>The proc filesystem</title>
218
219 <sect1><title>sysctl interface</title>
220!Ekernel/sysctl.c
221 </sect1>
4dc3b16b
PP
222
223 <sect1><title>proc filesystem interface</title>
224!Ifs/proc/base.c
225 </sect1>
1da177e4
LT
226 </chapter>
227
5b217fa7
RD
228 <chapter id="sysfs">
229 <title>The Filesystem for Exporting Kernel Objects</title>
230!Efs/sysfs/file.c
231!Efs/sysfs/symlink.c
232!Efs/sysfs/bin.c
233 </chapter>
234
1da177e4
LT
235 <chapter id="debugfs">
236 <title>The debugfs filesystem</title>
237
238 <sect1><title>debugfs interface</title>
239!Efs/debugfs/inode.c
240!Efs/debugfs/file.c
241 </sect1>
242 </chapter>
243
4c78a663
RD
244 <chapter id="relayfs">
245 <title>relay interface support</title>
246
247 <para>
248 Relay interface support
249 is designed to provide an efficient mechanism for tools and
250 facilities to relay large amounts of data from kernel space to
251 user space.
252 </para>
253
254 <sect1><title>relay interface</title>
255!Ekernel/relay.c
256!Ikernel/relay.c
257 </sect1>
258 </chapter>
259
1da177e4
LT
260 <chapter id="netcore">
261 <title>Linux Networking</title>
4dc3b16b
PP
262 <sect1><title>Networking Base Types</title>
263!Iinclude/linux/net.h
264 </sect1>
1da177e4
LT
265 <sect1><title>Socket Buffer Functions</title>
266!Iinclude/linux/skbuff.h
4dc3b16b
PP
267!Iinclude/net/sock.h
268!Enet/socket.c
1da177e4 269!Enet/core/skbuff.c
4dc3b16b
PP
270!Enet/core/sock.c
271!Enet/core/datagram.c
272!Enet/core/stream.c
1da177e4
LT
273 </sect1>
274 <sect1><title>Socket Filter</title>
275!Enet/core/filter.c
276 </sect1>
277 <sect1><title>Generic Network Statistics</title>
278!Iinclude/linux/gen_stats.h
279!Enet/core/gen_stats.c
280!Enet/core/gen_estimator.c
281 </sect1>
4dc3b16b
PP
282 <sect1><title>SUN RPC subsystem</title>
283<!-- The !D functionality is not perfect, garbage has to be protected by comments
284!Dnet/sunrpc/sunrpc_syms.c
285-->
286!Enet/sunrpc/xdr.c
287!Enet/sunrpc/svcsock.c
288!Enet/sunrpc/sched.c
289 </sect1>
1da177e4
LT
290 </chapter>
291
292 <chapter id="netdev">
293 <title>Network device support</title>
294 <sect1><title>Driver Support</title>
295!Enet/core/dev.c
c2da8aca 296!Enet/ethernet/eth.c
461ddf3b
RD
297!Iinclude/linux/etherdevice.h
298<!-- FIXME: Removed for now since no structured comments in source
299X!Enet/core/wireless.c
300-->
1da177e4
LT
301 </sect1>
302 <sect1><title>Synchronous PPP</title>
303!Edrivers/net/wan/syncppp.c
304 </sect1>
305 </chapter>
306
307 <chapter id="modload">
308 <title>Module Support</title>
309 <sect1><title>Module Loading</title>
310!Ekernel/kmod.c
311 </sect1>
312 <sect1><title>Inter Module support</title>
313 <para>
314 Refer to the file kernel/module.c for more information.
315 </para>
316<!-- FIXME: Removed for now since no structured comments in source
317X!Ekernel/module.c
318-->
319 </sect1>
320 </chapter>
321
322 <chapter id="hardware">
323 <title>Hardware Interfaces</title>
324 <sect1><title>Interrupt Handling</title>
8f2709b5 325!Ekernel/irq/manage.c
1da177e4
LT
326 </sect1>
327
eed34d0f
RD
328 <sect1><title>DMA Channels</title>
329!Ekernel/dma.c
330 </sect1>
331
4dc3b16b 332 <sect1><title>Resources Management</title>
2b54960b 333!Ikernel/resource.c
4dc3b16b
PP
334 </sect1>
335
1da177e4
LT
336 <sect1><title>MTRR Handling</title>
337!Earch/i386/kernel/cpu/mtrr/main.c
338 </sect1>
b0ef371e 339
1da177e4
LT
340 <sect1><title>PCI Support Library</title>
341!Edrivers/pci/pci.c
4dc3b16b
PP
342!Edrivers/pci/pci-driver.c
343!Edrivers/pci/remove.c
344!Edrivers/pci/pci-acpi.c
d75763d2 345!Edrivers/pci/search.c
4dc3b16b
PP
346!Edrivers/pci/msi.c
347!Edrivers/pci/bus.c
f05aab8e
RD
348<!-- FIXME: Removed for now since no structured comments in source
349X!Edrivers/pci/hotplug.c
350-->
4dc3b16b
PP
351!Edrivers/pci/probe.c
352!Edrivers/pci/rom.c
1da177e4
LT
353 </sect1>
354 <sect1><title>PCI Hotplug Support Library</title>
355!Edrivers/pci/hotplug/pci_hotplug_core.c
356 </sect1>
357 <sect1><title>MCA Architecture</title>
358 <sect2><title>MCA Device Functions</title>
359 <para>
360 Refer to the file arch/i386/kernel/mca.c for more information.
361 </para>
362<!-- FIXME: Removed for now since no structured comments in source
363X!Earch/i386/kernel/mca.c
364-->
365 </sect2>
366 <sect2><title>MCA Bus DMA</title>
367!Iinclude/asm-i386/mca_dma.h
368 </sect2>
369 </sect1>
370 </chapter>
371
b0ef371e
RD
372 <chapter id="firmware">
373 <title>Firmware Interfaces</title>
374 <sect1><title>DMI Interfaces</title>
375!Edrivers/firmware/dmi_scan.c
376 </sect1>
377 </chapter>
378
1da177e4
LT
379 <chapter id="security">
380 <title>Security Framework</title>
381!Esecurity/security.c
382 </chapter>
383
862f5f01
RD
384 <chapter id="audit">
385 <title>Audit Interfaces</title>
386!Ekernel/audit.c
387!Ikernel/auditsc.c
388!Ikernel/auditfilter.c
389 </chapter>
390
391 <chapter id="accounting">
392 <title>Accounting Framework</title>
393!Ikernel/acct.c
394 </chapter>
395
1da177e4
LT
396 <chapter id="pmfuncs">
397 <title>Power Management</title>
398!Ekernel/power/pm.c
399 </chapter>
400
4dc3b16b
PP
401 <chapter id="devdrivers">
402 <title>Device drivers infrastructure</title>
403 <sect1><title>Device Drivers Base</title>
404<!--
405X!Iinclude/linux/device.h
406-->
407!Edrivers/base/driver.c
4dc3b16b 408!Edrivers/base/core.c
78b2290f 409!Edrivers/base/class.c
4dc3b16b
PP
410!Edrivers/base/firmware_class.c
411!Edrivers/base/transport_class.c
412!Edrivers/base/dmapool.c
413<!-- Cannot be included, because
414 attribute_container_add_class_device_adapter
415 and attribute_container_classdev_to_container
416 exceed allowed 44 characters maximum
417X!Edrivers/base/attribute_container.c
418-->
419!Edrivers/base/sys.c
420<!--
421X!Edrivers/base/interface.c
422-->
423!Edrivers/base/platform.c
424!Edrivers/base/bus.c
425 </sect1>
426 <sect1><title>Device Drivers Power Management</title>
427!Edrivers/base/power/main.c
428!Edrivers/base/power/resume.c
429!Edrivers/base/power/suspend.c
430 </sect1>
431 <sect1><title>Device Drivers ACPI Support</title>
432<!-- Internal functions only
433X!Edrivers/acpi/sleep/main.c
434X!Edrivers/acpi/sleep/wakeup.c
435X!Edrivers/acpi/motherboard.c
436X!Edrivers/acpi/bus.c
437-->
438!Edrivers/acpi/scan.c
d758a8fa 439!Idrivers/acpi/scan.c
4dc3b16b
PP
440<!-- No correct structured comments
441X!Edrivers/acpi/pci_bind.c
442-->
443 </sect1>
444 <sect1><title>Device drivers PnP support</title>
445!Edrivers/pnp/core.c
446<!-- No correct structured comments
447X!Edrivers/pnp/system.c
448 -->
449!Edrivers/pnp/card.c
450!Edrivers/pnp/driver.c
451!Edrivers/pnp/manager.c
452!Edrivers/pnp/support.c
453 </sect1>
454 </chapter>
455
1da177e4
LT
456 <chapter id="blkdev">
457 <title>Block Devices</title>
1d193f4f 458!Eblock/ll_rw_blk.c
1da177e4
LT
459 </chapter>
460
cf3e43db
JC
461 <chapter id="chrdev">
462 <title>Char devices</title>
463!Efs/char_dev.c
464 </chapter>
465
1da177e4
LT
466 <chapter id="miscdev">
467 <title>Miscellaneous Devices</title>
468!Edrivers/char/misc.c
469 </chapter>
470
7d469722
RD
471 <chapter id="parportdev">
472 <title>Parallel Port Devices</title>
473!Iinclude/linux/parport.h
474!Edrivers/parport/ieee1284.c
475!Edrivers/parport/share.c
476!Idrivers/parport/daisy.c
477 </chapter>
478
1da177e4
LT
479 <chapter id="viddev">
480 <title>Video4Linux</title>
481!Edrivers/media/video/videodev.c
482 </chapter>
483
484 <chapter id="snddev">
485 <title>Sound Devices</title>
4dc3b16b 486!Iinclude/sound/core.h
1da177e4 487!Esound/sound_core.c
4dc3b16b
PP
488!Iinclude/sound/pcm.h
489!Esound/core/pcm.c
490!Esound/core/device.c
491!Esound/core/info.c
492!Esound/core/rawmidi.c
493!Esound/core/sound.c
494!Esound/core/memory.c
495!Esound/core/pcm_memory.c
496!Esound/core/init.c
497!Esound/core/isadma.c
498!Esound/core/control.c
499!Esound/core/pcm_lib.c
500!Esound/core/hwdep.c
501!Esound/core/pcm_native.c
502!Esound/core/memalloc.c
1da177e4
LT
503<!-- FIXME: Removed for now since no structured comments in source
504X!Isound/sound_firmware.c
505-->
506 </chapter>
507
508 <chapter id="uart16x50">
509 <title>16x50 UART Driver</title>
4dc3b16b 510!Iinclude/linux/serial_core.h
1da177e4
LT
511!Edrivers/serial/serial_core.c
512!Edrivers/serial/8250.c
513 </chapter>
514
515 <chapter id="z85230">
516 <title>Z85230 Support Library</title>
517!Edrivers/net/wan/z85230.c
518 </chapter>
519
520 <chapter id="fbdev">
521 <title>Frame Buffer Library</title>
522
523 <para>
524 The frame buffer drivers depend heavily on four data structures.
525 These structures are declared in include/linux/fb.h. They are
526 fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
527 The last three can be made available to and from userland.
528 </para>
529
530 <para>
531 fb_info defines the current state of a particular video card.
532 Inside fb_info, there exists a fb_ops structure which is a
533 collection of needed functions to make fbdev and fbcon work.
534 fb_info is only visible to the kernel.
535 </para>
536
537 <para>
538 fb_var_screeninfo is used to describe the features of a video card
539 that are user defined. With fb_var_screeninfo, things such as
540 depth and the resolution may be defined.
541 </para>
542
543 <para>
544 The next structure is fb_fix_screeninfo. This defines the
545 properties of a card that are created when a mode is set and can't
546 be changed otherwise. A good example of this is the start of the
547 frame buffer memory. This "locks" the address of the frame buffer
548 memory, so that it cannot be changed or moved.
549 </para>
550
551 <para>
552 The last structure is fb_monospecs. In the old API, there was
553 little importance for fb_monospecs. This allowed for forbidden things
554 such as setting a mode of 800x600 on a fix frequency monitor. With
555 the new API, fb_monospecs prevents such things, and if used
556 correctly, can prevent a monitor from being cooked. fb_monospecs
557 will not be useful until kernels 2.5.x.
558 </para>
559
560 <sect1><title>Frame Buffer Memory</title>
561!Edrivers/video/fbmem.c
562 </sect1>
4dc3b16b 563<!--
1da177e4 564 <sect1><title>Frame Buffer Console</title>
4dc3b16b 565X!Edrivers/video/console/fbcon.c
1da177e4 566 </sect1>
4dc3b16b 567-->
1da177e4
LT
568 <sect1><title>Frame Buffer Colormap</title>
569!Edrivers/video/fbcmap.c
570 </sect1>
571<!-- FIXME:
572 drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
573 out until somebody adds docs. KAO
574 <sect1><title>Frame Buffer Generic Functions</title>
575X!Idrivers/video/fbgen.c
576 </sect1>
577KAO -->
578 <sect1><title>Frame Buffer Video Mode Database</title>
579!Idrivers/video/modedb.c
580!Edrivers/video/modedb.c
581 </sect1>
582 <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
8f2709b5 583!Edrivers/video/macmodes.c
1da177e4
LT
584 </sect1>
585 <sect1><title>Frame Buffer Fonts</title>
586 <para>
587 Refer to the file drivers/video/console/fonts.c for more information.
588 </para>
589<!-- FIXME: Removed for now since no structured comments in source
590X!Idrivers/video/console/fonts.c
591-->
592 </sect1>
593 </chapter>
594</book>