Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 41 | <chapter id="adt"> |
| 42 | <title>Data Types</title> |
| 43 | <sect1><title>Doubly Linked Lists</title> |
| 44 | !Iinclude/linux/list.h |
| 45 | </sect1> |
| 46 | </chapter> |
| 47 | |
| 48 | <chapter id="libc"> |
| 49 | <title>Basic C Library Functions</title> |
| 50 | |
| 51 | <para> |
| 52 | When writing drivers, you cannot in general use routines which are |
| 53 | from the C Library. Some of the functions have been found generally |
| 54 | useful and they are listed below. The behaviour of these functions |
| 55 | may vary slightly from those defined by ANSI, and these deviations |
| 56 | are noted in the text. |
| 57 | </para> |
| 58 | |
| 59 | <sect1><title>String Conversions</title> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 60 | !Elib/vsprintf.c |
| 61 | </sect1> |
| 62 | <sect1><title>String Manipulation</title> |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 63 | <!-- All functions are exported at now |
| 64 | X!Ilib/string.c |
| 65 | --> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 66 | !Elib/string.c |
| 67 | </sect1> |
| 68 | <sect1><title>Bit Operations</title> |
Randy Dunlap | a1a739c | 2008-10-25 17:24:36 -0700 | [diff] [blame] | 69 | !Iarch/x86/include/asm/bitops.h |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 70 | </sect1> |
Randy Dunlap | 28e83ba | 2006-06-25 05:48:58 -0700 | [diff] [blame] | 71 | </chapter> |
| 72 | |
| 73 | <chapter id="kernel-lib"> |
| 74 | <title>Basic Kernel Library Functions</title> |
| 75 | |
| 76 | <para> |
| 77 | The Linux kernel provides more basic utility functions. |
| 78 | </para> |
| 79 | |
Randy Dunlap | 6e1907ff | 2006-06-25 05:48:57 -0700 | [diff] [blame] | 80 | <sect1><title>Bitmap Operations</title> |
| 81 | !Elib/bitmap.c |
| 82 | !Ilib/bitmap.c |
| 83 | </sect1> |
Randy Dunlap | 28e83ba | 2006-06-25 05:48:58 -0700 | [diff] [blame] | 84 | |
| 85 | <sect1><title>Command-line Parsing</title> |
| 86 | !Elib/cmdline.c |
| 87 | </sect1> |
Randy Dunlap | 2f72100 | 2006-06-25 05:48:59 -0700 | [diff] [blame] | 88 | |
Jan Nikitenko | ad24152 | 2007-07-17 04:04:03 -0700 | [diff] [blame] | 89 | <sect1 id="crc"><title>CRC Functions</title> |
| 90 | !Elib/crc7.c |
Randy Dunlap | 2f72100 | 2006-06-25 05:48:59 -0700 | [diff] [blame] | 91 | !Elib/crc16.c |
Jan Nikitenko | ad24152 | 2007-07-17 04:04:03 -0700 | [diff] [blame] | 92 | !Elib/crc-itu-t.c |
Randy Dunlap | 2f72100 | 2006-06-25 05:48:59 -0700 | [diff] [blame] | 93 | !Elib/crc32.c |
| 94 | !Elib/crc-ccitt.c |
| 95 | </sect1> |
Randy Dunlap | 56083ab | 2010-10-26 14:19:08 -0700 | [diff] [blame] | 96 | |
| 97 | <sect1 id="idr"><title>idr/ida Functions</title> |
| 98 | !Pinclude/linux/idr.h idr sync |
| 99 | !Plib/idr.c IDA description |
| 100 | !Elib/idr.c |
| 101 | </sect1> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 102 | </chapter> |
| 103 | |
| 104 | <chapter id="mm"> |
| 105 | <title>Memory Management in Linux</title> |
| 106 | <sect1><title>The Slab Cache</title> |
Paul Drynoff | 800590f | 2006-06-23 02:03:48 -0700 | [diff] [blame] | 107 | !Iinclude/linux/slab.h |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 108 | !Emm/slab.c |
| 109 | </sect1> |
| 110 | <sect1><title>User Space Memory Access</title> |
Randy Dunlap | a1a739c | 2008-10-25 17:24:36 -0700 | [diff] [blame] | 111 | !Iarch/x86/include/asm/uaccess_32.h |
Randy Dunlap | f3cf31a | 2007-10-12 21:17:23 -0700 | [diff] [blame] | 112 | !Earch/x86/lib/usercopy_32.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 113 | </sect1> |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 114 | <sect1><title>More Memory Management Functions</title> |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 115 | !Emm/readahead.c |
| 116 | !Emm/filemap.c |
| 117 | !Emm/memory.c |
| 118 | !Emm/vmalloc.c |
Randy Dunlap | 88ca3b9 | 2006-10-04 02:15:25 -0700 | [diff] [blame] | 119 | !Imm/page_alloc.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 120 | !Emm/mempool.c |
Randy Dunlap | a80a438b | 2008-02-06 16:29:55 -0800 | [diff] [blame] | 121 | !Emm/dmapool.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 122 | !Emm/page-writeback.c |
| 123 | !Emm/truncate.c |
| 124 | </sect1> |
| 125 | </chapter> |
| 126 | |
| 127 | |
| 128 | <chapter id="ipc"> |
| 129 | <title>Kernel IPC facilities</title> |
| 130 | |
| 131 | <sect1><title>IPC utilities</title> |
| 132 | !Iipc/util.c |
| 133 | </sect1> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 134 | </chapter> |
| 135 | |
| 136 | <chapter id="kfifo"> |
| 137 | <title>FIFO Buffer</title> |
| 138 | <sect1><title>kfifo interface</title> |
| 139 | !Iinclude/linux/kfifo.h |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 140 | </sect1> |
| 141 | </chapter> |
| 142 | |
Randy Dunlap | 5b217fa | 2006-09-29 01:59:10 -0700 | [diff] [blame] | 143 | <chapter id="relayfs"> |
| 144 | <title>relay interface support</title> |
| 145 | |
| 146 | <para> |
| 147 | Relay interface support |
| 148 | is designed to provide an efficient mechanism for tools and |
| 149 | facilities to relay large amounts of data from kernel space to |
| 150 | user space. |
| 151 | </para> |
| 152 | |
| 153 | <sect1><title>relay interface</title> |
| 154 | !Ekernel/relay.c |
| 155 | !Ikernel/relay.c |
| 156 | </sect1> |
| 157 | </chapter> |
| 158 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 159 | <chapter id="modload"> |
| 160 | <title>Module Support</title> |
| 161 | <sect1><title>Module Loading</title> |
| 162 | !Ekernel/kmod.c |
| 163 | </sect1> |
| 164 | <sect1><title>Inter Module support</title> |
| 165 | <para> |
| 166 | Refer to the file kernel/module.c for more information. |
| 167 | </para> |
| 168 | <!-- FIXME: Removed for now since no structured comments in source |
| 169 | X!Ekernel/module.c |
| 170 | --> |
| 171 | </sect1> |
| 172 | </chapter> |
| 173 | |
| 174 | <chapter id="hardware"> |
| 175 | <title>Hardware Interfaces</title> |
| 176 | <sect1><title>Interrupt Handling</title> |
Randy Dunlap | 8f2709b | 2005-11-07 01:01:05 -0800 | [diff] [blame] | 177 | !Ekernel/irq/manage.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 178 | </sect1> |
| 179 | |
Randy Dunlap | eed34d0 | 2006-10-03 01:13:50 -0700 | [diff] [blame] | 180 | <sect1><title>DMA Channels</title> |
| 181 | !Ekernel/dma.c |
| 182 | </sect1> |
| 183 | |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 184 | <sect1><title>Resources Management</title> |
Randy Dunlap | 2b54960 | 2006-07-30 03:03:40 -0700 | [diff] [blame] | 185 | !Ikernel/resource.c |
Randy Dunlap | e1ca66d1b | 2006-10-03 01:13:51 -0700 | [diff] [blame] | 186 | !Ekernel/resource.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 187 | </sect1> |
| 188 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 189 | <sect1><title>MTRR Handling</title> |
Randy Dunlap | f3cf31a | 2007-10-12 21:17:23 -0700 | [diff] [blame] | 190 | !Earch/x86/kernel/cpu/mtrr/main.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 191 | </sect1> |
Randy Dunlap | b0ef371 | 2006-06-25 05:49:18 -0700 | [diff] [blame] | 192 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 193 | <sect1><title>PCI Support Library</title> |
| 194 | !Edrivers/pci/pci.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 195 | !Edrivers/pci/pci-driver.c |
| 196 | !Edrivers/pci/remove.c |
Randy Dunlap | d75763d | 2006-07-30 03:03:41 -0700 | [diff] [blame] | 197 | !Edrivers/pci/search.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 198 | !Edrivers/pci/msi.c |
| 199 | !Edrivers/pci/bus.c |
Randy Dunlap | cffb2fa | 2009-04-10 15:17:50 -0700 | [diff] [blame] | 200 | !Edrivers/pci/access.c |
| 201 | !Edrivers/pci/irq.c |
| 202 | !Edrivers/pci/htirq.c |
Randy Dunlap | f05aab8 | 2005-10-23 11:58:19 -0700 | [diff] [blame] | 203 | <!-- FIXME: Removed for now since no structured comments in source |
| 204 | X!Edrivers/pci/hotplug.c |
| 205 | --> |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 206 | !Edrivers/pci/probe.c |
Randy Dunlap | cffb2fa | 2009-04-10 15:17:50 -0700 | [diff] [blame] | 207 | !Edrivers/pci/slot.c |
Pavel Pisa | 4dc3b16 | 2005-05-01 08:59:25 -0700 | [diff] [blame] | 208 | !Edrivers/pci/rom.c |
Yu Zhao | 15b49be | 2009-03-20 11:25:18 +0800 | [diff] [blame] | 209 | !Edrivers/pci/iov.c |
Randy Dunlap | cffb2fa | 2009-04-10 15:17:50 -0700 | [diff] [blame] | 210 | !Idrivers/pci/pci-sysfs.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 211 | </sect1> |
| 212 | <sect1><title>PCI Hotplug Support Library</title> |
| 213 | !Edrivers/pci/hotplug/pci_hotplug_core.c |
| 214 | </sect1> |
| 215 | <sect1><title>MCA Architecture</title> |
| 216 | <sect2><title>MCA Device Functions</title> |
| 217 | <para> |
Randy Dunlap | f3cf31a | 2007-10-12 21:17:23 -0700 | [diff] [blame] | 218 | Refer to the file arch/x86/kernel/mca_32.c for more information. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 219 | </para> |
| 220 | <!-- FIXME: Removed for now since no structured comments in source |
Randy Dunlap | f3cf31a | 2007-10-12 21:17:23 -0700 | [diff] [blame] | 221 | X!Earch/x86/kernel/mca_32.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 222 | --> |
| 223 | </sect2> |
| 224 | <sect2><title>MCA Bus DMA</title> |
Randy Dunlap | a1a739c | 2008-10-25 17:24:36 -0700 | [diff] [blame] | 225 | !Iarch/x86/include/asm/mca_dma.h |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 226 | </sect2> |
| 227 | </sect1> |
| 228 | </chapter> |
| 229 | |
Randy Dunlap | b0ef371 | 2006-06-25 05:49:18 -0700 | [diff] [blame] | 230 | <chapter id="firmware"> |
| 231 | <title>Firmware Interfaces</title> |
| 232 | <sect1><title>DMI Interfaces</title> |
| 233 | !Edrivers/firmware/dmi_scan.c |
| 234 | </sect1> |
Randy Dunlap | 6e8c818 | 2007-02-10 01:46:03 -0800 | [diff] [blame] | 235 | <sect1><title>EDD Interfaces</title> |
| 236 | !Idrivers/firmware/edd.c |
| 237 | </sect1> |
Randy Dunlap | b0ef371 | 2006-06-25 05:49:18 -0700 | [diff] [blame] | 238 | </chapter> |
| 239 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 240 | <chapter id="security"> |
| 241 | <title>Security Framework</title> |
James Morris | 20510f2 | 2007-10-16 23:31:32 -0700 | [diff] [blame] | 242 | !Isecurity/security.c |
Randy Dunlap | 3f23d81 | 2008-08-17 21:44:22 -0700 | [diff] [blame] | 243 | !Esecurity/inode.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 244 | </chapter> |
| 245 | |
Randy Dunlap | 862f5f0 | 2006-06-23 02:05:52 -0700 | [diff] [blame] | 246 | <chapter id="audit"> |
| 247 | <title>Audit Interfaces</title> |
| 248 | !Ekernel/audit.c |
| 249 | !Ikernel/auditsc.c |
| 250 | !Ikernel/auditfilter.c |
| 251 | </chapter> |
| 252 | |
| 253 | <chapter id="accounting"> |
| 254 | <title>Accounting Framework</title> |
| 255 | !Ikernel/acct.c |
| 256 | </chapter> |
| 257 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 258 | <chapter id="blkdev"> |
| 259 | <title>Block Devices</title> |
Randy Dunlap | caf03fe | 2008-01-30 11:51:00 -0800 | [diff] [blame] | 260 | !Eblock/blk-core.c |
Randy Dunlap | 5d87a05 | 2008-02-20 09:01:22 +0100 | [diff] [blame] | 261 | !Iblock/blk-core.c |
Randy Dunlap | caf03fe | 2008-01-30 11:51:00 -0800 | [diff] [blame] | 262 | !Eblock/blk-map.c |
| 263 | !Iblock/blk-sysfs.c |
| 264 | !Eblock/blk-settings.c |
| 265 | !Eblock/blk-exec.c |
Mike Snitzer | 4d15290 | 2010-10-21 14:54:19 +0200 | [diff] [blame] | 266 | !Eblock/blk-flush.c |
| 267 | !Eblock/blk-lib.c |
Randy Dunlap | caf03fe | 2008-01-30 11:51:00 -0800 | [diff] [blame] | 268 | !Eblock/blk-tag.c |
Randy Dunlap | 5d87a05 | 2008-02-20 09:01:22 +0100 | [diff] [blame] | 269 | !Iblock/blk-tag.c |
Randy Dunlap | 710027a | 2008-08-19 20:13:11 +0200 | [diff] [blame] | 270 | !Eblock/blk-integrity.c |
Randy Dunlap | 88cacbb | 2009-04-05 15:45:34 -0700 | [diff] [blame] | 271 | !Ikernel/trace/blktrace.c |
Randy Dunlap | 710027a | 2008-08-19 20:13:11 +0200 | [diff] [blame] | 272 | !Iblock/genhd.c |
| 273 | !Eblock/genhd.c |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 274 | </chapter> |
| 275 | |
Jonathan Corbet | cf3e43d | 2006-09-29 02:00:44 -0700 | [diff] [blame] | 276 | <chapter id="chrdev"> |
| 277 | <title>Char devices</title> |
| 278 | !Efs/char_dev.c |
| 279 | </chapter> |
| 280 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 281 | <chapter id="miscdev"> |
| 282 | <title>Miscellaneous Devices</title> |
| 283 | !Edrivers/char/misc.c |
| 284 | </chapter> |
| 285 | |
David Brownell | e275ac4 | 2008-04-28 02:11:56 -0700 | [diff] [blame] | 286 | <chapter id="clk"> |
| 287 | <title>Clock Framework</title> |
| 288 | |
| 289 | <para> |
| 290 | The clock framework defines programming interfaces to support |
| 291 | software management of the system clock tree. |
| 292 | This framework is widely used with System-On-Chip (SOC) platforms |
| 293 | to support power management and various devices which may need |
| 294 | custom clock rates. |
| 295 | Note that these "clocks" don't relate to timekeeping or real |
| 296 | time clocks (RTCs), each of which have separate frameworks. |
| 297 | These <structname>struct clk</structname> instances may be used |
| 298 | to manage for example a 96 MHz signal that is used to shift bits |
| 299 | into and out of peripherals or busses, or otherwise trigger |
| 300 | synchronous state machine transitions in system hardware. |
| 301 | </para> |
| 302 | |
| 303 | <para> |
| 304 | Power management is supported by explicit software clock gating: |
| 305 | unused clocks are disabled, so the system doesn't waste power |
| 306 | changing the state of transistors that aren't in active use. |
| 307 | On some systems this may be backed by hardware clock gating, |
| 308 | where clocks are gated without being disabled in software. |
| 309 | Sections of chips that are powered but not clocked may be able |
| 310 | to retain their last state. |
| 311 | This low power state is often called a <emphasis>retention |
| 312 | mode</emphasis>. |
| 313 | This mode still incurs leakage currents, especially with finer |
| 314 | circuit geometries, but for CMOS circuits power is mostly used |
| 315 | by clocked state changes. |
| 316 | </para> |
| 317 | |
| 318 | <para> |
| 319 | Power-aware drivers only enable their clocks when the device |
| 320 | they manage is in active use. Also, system sleep states often |
| 321 | differ according to which clock domains are active: while a |
| 322 | "standby" state may allow wakeup from several active domains, a |
| 323 | "mem" (suspend-to-RAM) state may require a more wholesale shutdown |
| 324 | of clocks derived from higher speed PLLs and oscillators, limiting |
| 325 | the number of possible wakeup event sources. A driver's suspend |
| 326 | method may need to be aware of system-specific clock constraints |
| 327 | on the target sleep state. |
| 328 | </para> |
| 329 | |
| 330 | <para> |
| 331 | Some platforms support programmable clock generators. These |
| 332 | can be used by external chips of various kinds, such as other |
| 333 | CPUs, multimedia codecs, and devices with strict requirements |
| 334 | for interface clocking. |
| 335 | </para> |
| 336 | |
| 337 | !Iinclude/linux/clk.h |
| 338 | </chapter> |
| 339 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 340 | </book> |