Commit | Line | Data |
---|---|---|
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 | ||
1da177e4 LT |
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> | |
1da177e4 | 60 | !Elib/vsprintf.c |
4c925d60 EZ |
61 | !Finclude/linux/kernel.h kstrtol |
62 | !Finclude/linux/kernel.h kstrtoul | |
63 | !Elib/kstrtox.c | |
1da177e4 LT |
64 | </sect1> |
65 | <sect1><title>String Manipulation</title> | |
4dc3b16b PP |
66 | <!-- All functions are exported at now |
67 | X!Ilib/string.c | |
68 | --> | |
1da177e4 LT |
69 | !Elib/string.c |
70 | </sect1> | |
71 | <sect1><title>Bit Operations</title> | |
a1a739c5 | 72 | !Iarch/x86/include/asm/bitops.h |
1da177e4 | 73 | </sect1> |
28e83baa RD |
74 | </chapter> |
75 | ||
76 | <chapter id="kernel-lib"> | |
77 | <title>Basic Kernel Library Functions</title> | |
78 | ||
79 | <para> | |
80 | The Linux kernel provides more basic utility functions. | |
81 | </para> | |
82 | ||
6e1907ff RD |
83 | <sect1><title>Bitmap Operations</title> |
84 | !Elib/bitmap.c | |
85 | !Ilib/bitmap.c | |
86 | </sect1> | |
28e83baa RD |
87 | |
88 | <sect1><title>Command-line Parsing</title> | |
89 | !Elib/cmdline.c | |
90 | </sect1> | |
2f72100c | 91 | |
ad241528 JN |
92 | <sect1 id="crc"><title>CRC Functions</title> |
93 | !Elib/crc7.c | |
2f72100c | 94 | !Elib/crc16.c |
ad241528 | 95 | !Elib/crc-itu-t.c |
2f72100c RD |
96 | !Elib/crc32.c |
97 | !Elib/crc-ccitt.c | |
98 | </sect1> | |
56083ab1 RD |
99 | |
100 | <sect1 id="idr"><title>idr/ida Functions</title> | |
101 | !Pinclude/linux/idr.h idr sync | |
102 | !Plib/idr.c IDA description | |
103 | !Elib/idr.c | |
104 | </sect1> | |
1da177e4 LT |
105 | </chapter> |
106 | ||
107 | <chapter id="mm"> | |
108 | <title>Memory Management in Linux</title> | |
109 | <sect1><title>The Slab Cache</title> | |
800590f5 | 110 | !Iinclude/linux/slab.h |
1da177e4 | 111 | !Emm/slab.c |
06660294 | 112 | !Emm/util.c |
1da177e4 LT |
113 | </sect1> |
114 | <sect1><title>User Space Memory Access</title> | |
a1a739c5 | 115 | !Iarch/x86/include/asm/uaccess_32.h |
f3cf31ad | 116 | !Earch/x86/lib/usercopy_32.c |
1da177e4 | 117 | </sect1> |
4dc3b16b | 118 | <sect1><title>More Memory Management Functions</title> |
4dc3b16b PP |
119 | !Emm/readahead.c |
120 | !Emm/filemap.c | |
121 | !Emm/memory.c | |
122 | !Emm/vmalloc.c | |
88ca3b94 | 123 | !Imm/page_alloc.c |
4dc3b16b | 124 | !Emm/mempool.c |
a80a438b | 125 | !Emm/dmapool.c |
4dc3b16b PP |
126 | !Emm/page-writeback.c |
127 | !Emm/truncate.c | |
128 | </sect1> | |
129 | </chapter> | |
130 | ||
131 | ||
132 | <chapter id="ipc"> | |
133 | <title>Kernel IPC facilities</title> | |
134 | ||
135 | <sect1><title>IPC utilities</title> | |
136 | !Iipc/util.c | |
137 | </sect1> | |
1da177e4 LT |
138 | </chapter> |
139 | ||
140 | <chapter id="kfifo"> | |
141 | <title>FIFO Buffer</title> | |
142 | <sect1><title>kfifo interface</title> | |
143 | !Iinclude/linux/kfifo.h | |
1da177e4 LT |
144 | </sect1> |
145 | </chapter> | |
146 | ||
4c78a663 RD |
147 | <chapter id="relayfs"> |
148 | <title>relay interface support</title> | |
149 | ||
150 | <para> | |
151 | Relay interface support | |
152 | is designed to provide an efficient mechanism for tools and | |
153 | facilities to relay large amounts of data from kernel space to | |
154 | user space. | |
155 | </para> | |
156 | ||
157 | <sect1><title>relay interface</title> | |
158 | !Ekernel/relay.c | |
159 | !Ikernel/relay.c | |
160 | </sect1> | |
161 | </chapter> | |
162 | ||
1da177e4 LT |
163 | <chapter id="modload"> |
164 | <title>Module Support</title> | |
165 | <sect1><title>Module Loading</title> | |
166 | !Ekernel/kmod.c | |
167 | </sect1> | |
168 | <sect1><title>Inter Module support</title> | |
169 | <para> | |
170 | Refer to the file kernel/module.c for more information. | |
171 | </para> | |
172 | <!-- FIXME: Removed for now since no structured comments in source | |
173 | X!Ekernel/module.c | |
174 | --> | |
175 | </sect1> | |
176 | </chapter> | |
177 | ||
178 | <chapter id="hardware"> | |
179 | <title>Hardware Interfaces</title> | |
180 | <sect1><title>Interrupt Handling</title> | |
8f2709b5 | 181 | !Ekernel/irq/manage.c |
1da177e4 LT |
182 | </sect1> |
183 | ||
eed34d0f RD |
184 | <sect1><title>DMA Channels</title> |
185 | !Ekernel/dma.c | |
186 | </sect1> | |
187 | ||
4dc3b16b | 188 | <sect1><title>Resources Management</title> |
2b54960b | 189 | !Ikernel/resource.c |
e1ca66d1 | 190 | !Ekernel/resource.c |
4dc3b16b PP |
191 | </sect1> |
192 | ||
1da177e4 | 193 | <sect1><title>MTRR Handling</title> |
f3cf31ad | 194 | !Earch/x86/kernel/cpu/mtrr/main.c |
1da177e4 | 195 | </sect1> |
b0ef371e | 196 | |
1da177e4 LT |
197 | <sect1><title>PCI Support Library</title> |
198 | !Edrivers/pci/pci.c | |
4dc3b16b PP |
199 | !Edrivers/pci/pci-driver.c |
200 | !Edrivers/pci/remove.c | |
d75763d2 | 201 | !Edrivers/pci/search.c |
4dc3b16b PP |
202 | !Edrivers/pci/msi.c |
203 | !Edrivers/pci/bus.c | |
cffb2faf RD |
204 | !Edrivers/pci/access.c |
205 | !Edrivers/pci/irq.c | |
206 | !Edrivers/pci/htirq.c | |
f05aab8e RD |
207 | <!-- FIXME: Removed for now since no structured comments in source |
208 | X!Edrivers/pci/hotplug.c | |
209 | --> | |
4dc3b16b | 210 | !Edrivers/pci/probe.c |
cffb2faf | 211 | !Edrivers/pci/slot.c |
4dc3b16b | 212 | !Edrivers/pci/rom.c |
15b49bee | 213 | !Edrivers/pci/iov.c |
cffb2faf | 214 | !Idrivers/pci/pci-sysfs.c |
1da177e4 LT |
215 | </sect1> |
216 | <sect1><title>PCI Hotplug Support Library</title> | |
217 | !Edrivers/pci/hotplug/pci_hotplug_core.c | |
218 | </sect1> | |
1da177e4 LT |
219 | </chapter> |
220 | ||
b0ef371e RD |
221 | <chapter id="firmware"> |
222 | <title>Firmware Interfaces</title> | |
223 | <sect1><title>DMI Interfaces</title> | |
224 | !Edrivers/firmware/dmi_scan.c | |
225 | </sect1> | |
6e8c8188 RD |
226 | <sect1><title>EDD Interfaces</title> |
227 | !Idrivers/firmware/edd.c | |
228 | </sect1> | |
b0ef371e RD |
229 | </chapter> |
230 | ||
1da177e4 LT |
231 | <chapter id="security"> |
232 | <title>Security Framework</title> | |
20510f2f | 233 | !Isecurity/security.c |
3f23d815 | 234 | !Esecurity/inode.c |
1da177e4 LT |
235 | </chapter> |
236 | ||
862f5f01 RD |
237 | <chapter id="audit"> |
238 | <title>Audit Interfaces</title> | |
239 | !Ekernel/audit.c | |
240 | !Ikernel/auditsc.c | |
241 | !Ikernel/auditfilter.c | |
242 | </chapter> | |
243 | ||
244 | <chapter id="accounting"> | |
245 | <title>Accounting Framework</title> | |
246 | !Ikernel/acct.c | |
247 | </chapter> | |
248 | ||
1da177e4 LT |
249 | <chapter id="blkdev"> |
250 | <title>Block Devices</title> | |
caf03feb | 251 | !Eblock/blk-core.c |
5d87a052 | 252 | !Iblock/blk-core.c |
caf03feb RD |
253 | !Eblock/blk-map.c |
254 | !Iblock/blk-sysfs.c | |
255 | !Eblock/blk-settings.c | |
256 | !Eblock/blk-exec.c | |
4d152904 MS |
257 | !Eblock/blk-flush.c |
258 | !Eblock/blk-lib.c | |
caf03feb | 259 | !Eblock/blk-tag.c |
5d87a052 | 260 | !Iblock/blk-tag.c |
710027a4 | 261 | !Eblock/blk-integrity.c |
88cacbb2 | 262 | !Ikernel/trace/blktrace.c |
710027a4 RD |
263 | !Iblock/genhd.c |
264 | !Eblock/genhd.c | |
1da177e4 LT |
265 | </chapter> |
266 | ||
cf3e43db JC |
267 | <chapter id="chrdev"> |
268 | <title>Char devices</title> | |
269 | !Efs/char_dev.c | |
270 | </chapter> | |
271 | ||
1da177e4 LT |
272 | <chapter id="miscdev"> |
273 | <title>Miscellaneous Devices</title> | |
274 | !Edrivers/char/misc.c | |
275 | </chapter> | |
276 | ||
e275ac47 DB |
277 | <chapter id="clk"> |
278 | <title>Clock Framework</title> | |
279 | ||
280 | <para> | |
281 | The clock framework defines programming interfaces to support | |
282 | software management of the system clock tree. | |
283 | This framework is widely used with System-On-Chip (SOC) platforms | |
284 | to support power management and various devices which may need | |
285 | custom clock rates. | |
286 | Note that these "clocks" don't relate to timekeeping or real | |
287 | time clocks (RTCs), each of which have separate frameworks. | |
288 | These <structname>struct clk</structname> instances may be used | |
289 | to manage for example a 96 MHz signal that is used to shift bits | |
290 | into and out of peripherals or busses, or otherwise trigger | |
291 | synchronous state machine transitions in system hardware. | |
292 | </para> | |
293 | ||
294 | <para> | |
295 | Power management is supported by explicit software clock gating: | |
296 | unused clocks are disabled, so the system doesn't waste power | |
297 | changing the state of transistors that aren't in active use. | |
298 | On some systems this may be backed by hardware clock gating, | |
299 | where clocks are gated without being disabled in software. | |
300 | Sections of chips that are powered but not clocked may be able | |
301 | to retain their last state. | |
302 | This low power state is often called a <emphasis>retention | |
303 | mode</emphasis>. | |
304 | This mode still incurs leakage currents, especially with finer | |
305 | circuit geometries, but for CMOS circuits power is mostly used | |
306 | by clocked state changes. | |
307 | </para> | |
308 | ||
309 | <para> | |
310 | Power-aware drivers only enable their clocks when the device | |
311 | they manage is in active use. Also, system sleep states often | |
312 | differ according to which clock domains are active: while a | |
313 | "standby" state may allow wakeup from several active domains, a | |
314 | "mem" (suspend-to-RAM) state may require a more wholesale shutdown | |
315 | of clocks derived from higher speed PLLs and oscillators, limiting | |
316 | the number of possible wakeup event sources. A driver's suspend | |
317 | method may need to be aware of system-specific clock constraints | |
318 | on the target sleep state. | |
319 | </para> | |
320 | ||
321 | <para> | |
322 | Some platforms support programmable clock generators. These | |
323 | can be used by external chips of various kinds, such as other | |
324 | CPUs, multimedia codecs, and devices with strict requirements | |
325 | for interface clocking. | |
326 | </para> | |
327 | ||
328 | !Iinclude/linux/clk.h | |
329 | </chapter> | |
330 | ||
1da177e4 | 331 | </book> |