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 LT |
60 | !Elib/vsprintf.c |
61 | </sect1> | |
62 | <sect1><title>String Manipulation</title> | |
4dc3b16b PP |
63 | <!-- All functions are exported at now |
64 | X!Ilib/string.c | |
65 | --> | |
1da177e4 LT |
66 | !Elib/string.c |
67 | </sect1> | |
68 | <sect1><title>Bit Operations</title> | |
a1a739c5 | 69 | !Iarch/x86/include/asm/bitops.h |
1da177e4 | 70 | </sect1> |
28e83baa RD |
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 | ||
6e1907ff RD |
80 | <sect1><title>Bitmap Operations</title> |
81 | !Elib/bitmap.c | |
82 | !Ilib/bitmap.c | |
83 | </sect1> | |
28e83baa RD |
84 | |
85 | <sect1><title>Command-line Parsing</title> | |
86 | !Elib/cmdline.c | |
87 | </sect1> | |
2f72100c | 88 | |
ad241528 JN |
89 | <sect1 id="crc"><title>CRC Functions</title> |
90 | !Elib/crc7.c | |
2f72100c | 91 | !Elib/crc16.c |
ad241528 | 92 | !Elib/crc-itu-t.c |
2f72100c RD |
93 | !Elib/crc32.c |
94 | !Elib/crc-ccitt.c | |
95 | </sect1> | |
56083ab1 RD |
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> | |
1da177e4 LT |
102 | </chapter> |
103 | ||
104 | <chapter id="mm"> | |
105 | <title>Memory Management in Linux</title> | |
106 | <sect1><title>The Slab Cache</title> | |
800590f5 | 107 | !Iinclude/linux/slab.h |
1da177e4 LT |
108 | !Emm/slab.c |
109 | </sect1> | |
110 | <sect1><title>User Space Memory Access</title> | |
a1a739c5 | 111 | !Iarch/x86/include/asm/uaccess_32.h |
f3cf31ad | 112 | !Earch/x86/lib/usercopy_32.c |
1da177e4 | 113 | </sect1> |
4dc3b16b | 114 | <sect1><title>More Memory Management Functions</title> |
4dc3b16b PP |
115 | !Emm/readahead.c |
116 | !Emm/filemap.c | |
117 | !Emm/memory.c | |
118 | !Emm/vmalloc.c | |
88ca3b94 | 119 | !Imm/page_alloc.c |
4dc3b16b | 120 | !Emm/mempool.c |
a80a438b | 121 | !Emm/dmapool.c |
4dc3b16b PP |
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> | |
1da177e4 LT |
134 | </chapter> |
135 | ||
136 | <chapter id="kfifo"> | |
137 | <title>FIFO Buffer</title> | |
138 | <sect1><title>kfifo interface</title> | |
139 | !Iinclude/linux/kfifo.h | |
1da177e4 LT |
140 | </sect1> |
141 | </chapter> | |
142 | ||
4c78a663 RD |
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 | ||
1da177e4 LT |
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> | |
8f2709b5 | 177 | !Ekernel/irq/manage.c |
1da177e4 LT |
178 | </sect1> |
179 | ||
eed34d0f RD |
180 | <sect1><title>DMA Channels</title> |
181 | !Ekernel/dma.c | |
182 | </sect1> | |
183 | ||
4dc3b16b | 184 | <sect1><title>Resources Management</title> |
2b54960b | 185 | !Ikernel/resource.c |
e1ca66d1 | 186 | !Ekernel/resource.c |
4dc3b16b PP |
187 | </sect1> |
188 | ||
1da177e4 | 189 | <sect1><title>MTRR Handling</title> |
f3cf31ad | 190 | !Earch/x86/kernel/cpu/mtrr/main.c |
1da177e4 | 191 | </sect1> |
b0ef371e | 192 | |
1da177e4 LT |
193 | <sect1><title>PCI Support Library</title> |
194 | !Edrivers/pci/pci.c | |
4dc3b16b PP |
195 | !Edrivers/pci/pci-driver.c |
196 | !Edrivers/pci/remove.c | |
d75763d2 | 197 | !Edrivers/pci/search.c |
4dc3b16b PP |
198 | !Edrivers/pci/msi.c |
199 | !Edrivers/pci/bus.c | |
cffb2faf RD |
200 | !Edrivers/pci/access.c |
201 | !Edrivers/pci/irq.c | |
202 | !Edrivers/pci/htirq.c | |
f05aab8e RD |
203 | <!-- FIXME: Removed for now since no structured comments in source |
204 | X!Edrivers/pci/hotplug.c | |
205 | --> | |
4dc3b16b | 206 | !Edrivers/pci/probe.c |
cffb2faf | 207 | !Edrivers/pci/slot.c |
4dc3b16b | 208 | !Edrivers/pci/rom.c |
15b49bee | 209 | !Edrivers/pci/iov.c |
cffb2faf | 210 | !Idrivers/pci/pci-sysfs.c |
1da177e4 LT |
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> | |
f3cf31ad | 218 | Refer to the file arch/x86/kernel/mca_32.c for more information. |
1da177e4 LT |
219 | </para> |
220 | <!-- FIXME: Removed for now since no structured comments in source | |
f3cf31ad | 221 | X!Earch/x86/kernel/mca_32.c |
1da177e4 LT |
222 | --> |
223 | </sect2> | |
224 | <sect2><title>MCA Bus DMA</title> | |
a1a739c5 | 225 | !Iarch/x86/include/asm/mca_dma.h |
1da177e4 LT |
226 | </sect2> |
227 | </sect1> | |
228 | </chapter> | |
229 | ||
b0ef371e RD |
230 | <chapter id="firmware"> |
231 | <title>Firmware Interfaces</title> | |
232 | <sect1><title>DMI Interfaces</title> | |
233 | !Edrivers/firmware/dmi_scan.c | |
234 | </sect1> | |
6e8c8188 RD |
235 | <sect1><title>EDD Interfaces</title> |
236 | !Idrivers/firmware/edd.c | |
237 | </sect1> | |
b0ef371e RD |
238 | </chapter> |
239 | ||
1da177e4 LT |
240 | <chapter id="security"> |
241 | <title>Security Framework</title> | |
20510f2f | 242 | !Isecurity/security.c |
3f23d815 | 243 | !Esecurity/inode.c |
1da177e4 LT |
244 | </chapter> |
245 | ||
862f5f01 RD |
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 | ||
1da177e4 LT |
258 | <chapter id="blkdev"> |
259 | <title>Block Devices</title> | |
caf03feb | 260 | !Eblock/blk-core.c |
5d87a052 | 261 | !Iblock/blk-core.c |
caf03feb RD |
262 | !Eblock/blk-map.c |
263 | !Iblock/blk-sysfs.c | |
264 | !Eblock/blk-settings.c | |
265 | !Eblock/blk-exec.c | |
4d152904 MS |
266 | !Eblock/blk-flush.c |
267 | !Eblock/blk-lib.c | |
caf03feb | 268 | !Eblock/blk-tag.c |
5d87a052 | 269 | !Iblock/blk-tag.c |
710027a4 | 270 | !Eblock/blk-integrity.c |
88cacbb2 | 271 | !Ikernel/trace/blktrace.c |
710027a4 RD |
272 | !Iblock/genhd.c |
273 | !Eblock/genhd.c | |
1da177e4 LT |
274 | </chapter> |
275 | ||
cf3e43db JC |
276 | <chapter id="chrdev"> |
277 | <title>Char devices</title> | |
278 | !Efs/char_dev.c | |
279 | </chapter> | |
280 | ||
1da177e4 LT |
281 | <chapter id="miscdev"> |
282 | <title>Miscellaneous Devices</title> | |
283 | !Edrivers/char/misc.c | |
284 | </chapter> | |
285 | ||
e275ac47 DB |
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 | ||
1da177e4 | 340 | </book> |