]>
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 | ||
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> | |
f3cf31ad | 48 | !Iinclude/asm-x86/atomic_32.h |
8f731f7d | 49 | !Iinclude/asm-x86/unaligned.h |
1da177e4 LT |
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 | <!-- | |
74 | X!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 | ||
d3e6975e RD |
87 | <sect1><title>Device Resource Management</title> |
88 | !Edrivers/base/devres.c | |
89 | </sect1> | |
90 | ||
1da177e4 LT |
91 | </chapter> |
92 | ||
93 | <chapter id="adt"> | |
94 | <title>Data Types</title> | |
95 | <sect1><title>Doubly Linked Lists</title> | |
96 | !Iinclude/linux/list.h | |
97 | </sect1> | |
98 | </chapter> | |
99 | ||
100 | <chapter id="libc"> | |
101 | <title>Basic C Library Functions</title> | |
102 | ||
103 | <para> | |
104 | When writing drivers, you cannot in general use routines which are | |
105 | from the C Library. Some of the functions have been found generally | |
106 | useful and they are listed below. The behaviour of these functions | |
107 | may vary slightly from those defined by ANSI, and these deviations | |
108 | are noted in the text. | |
109 | </para> | |
110 | ||
111 | <sect1><title>String Conversions</title> | |
112 | !Ilib/vsprintf.c | |
113 | !Elib/vsprintf.c | |
114 | </sect1> | |
115 | <sect1><title>String Manipulation</title> | |
4dc3b16b PP |
116 | <!-- All functions are exported at now |
117 | X!Ilib/string.c | |
118 | --> | |
1da177e4 LT |
119 | !Elib/string.c |
120 | </sect1> | |
121 | <sect1><title>Bit Operations</title> | |
f3cf31ad | 122 | !Iinclude/asm-x86/bitops_32.h |
1da177e4 | 123 | </sect1> |
28e83baa RD |
124 | </chapter> |
125 | ||
126 | <chapter id="kernel-lib"> | |
127 | <title>Basic Kernel Library Functions</title> | |
128 | ||
129 | <para> | |
130 | The Linux kernel provides more basic utility functions. | |
131 | </para> | |
132 | ||
6e1907ff RD |
133 | <sect1><title>Bitmap Operations</title> |
134 | !Elib/bitmap.c | |
135 | !Ilib/bitmap.c | |
136 | </sect1> | |
28e83baa RD |
137 | |
138 | <sect1><title>Command-line Parsing</title> | |
139 | !Elib/cmdline.c | |
140 | </sect1> | |
2f72100c | 141 | |
ad241528 JN |
142 | <sect1 id="crc"><title>CRC Functions</title> |
143 | !Elib/crc7.c | |
2f72100c | 144 | !Elib/crc16.c |
ad241528 | 145 | !Elib/crc-itu-t.c |
2f72100c RD |
146 | !Elib/crc32.c |
147 | !Elib/crc-ccitt.c | |
148 | </sect1> | |
1da177e4 LT |
149 | </chapter> |
150 | ||
151 | <chapter id="mm"> | |
152 | <title>Memory Management in Linux</title> | |
153 | <sect1><title>The Slab Cache</title> | |
800590f5 | 154 | !Iinclude/linux/slab.h |
1da177e4 LT |
155 | !Emm/slab.c |
156 | </sect1> | |
157 | <sect1><title>User Space Memory Access</title> | |
f3cf31ad RD |
158 | !Iinclude/asm-x86/uaccess_32.h |
159 | !Earch/x86/lib/usercopy_32.c | |
1da177e4 | 160 | </sect1> |
4dc3b16b | 161 | <sect1><title>More Memory Management Functions</title> |
4dc3b16b PP |
162 | !Emm/readahead.c |
163 | !Emm/filemap.c | |
164 | !Emm/memory.c | |
165 | !Emm/vmalloc.c | |
88ca3b94 | 166 | !Imm/page_alloc.c |
4dc3b16b | 167 | !Emm/mempool.c |
a80a438b | 168 | !Emm/dmapool.c |
4dc3b16b PP |
169 | !Emm/page-writeback.c |
170 | !Emm/truncate.c | |
171 | </sect1> | |
172 | </chapter> | |
173 | ||
174 | ||
175 | <chapter id="ipc"> | |
176 | <title>Kernel IPC facilities</title> | |
177 | ||
178 | <sect1><title>IPC utilities</title> | |
179 | !Iipc/util.c | |
180 | </sect1> | |
1da177e4 LT |
181 | </chapter> |
182 | ||
183 | <chapter id="kfifo"> | |
184 | <title>FIFO Buffer</title> | |
185 | <sect1><title>kfifo interface</title> | |
186 | !Iinclude/linux/kfifo.h | |
187 | !Ekernel/kfifo.c | |
188 | </sect1> | |
189 | </chapter> | |
190 | ||
4c78a663 RD |
191 | <chapter id="relayfs"> |
192 | <title>relay interface support</title> | |
193 | ||
194 | <para> | |
195 | Relay interface support | |
196 | is designed to provide an efficient mechanism for tools and | |
197 | facilities to relay large amounts of data from kernel space to | |
198 | user space. | |
199 | </para> | |
200 | ||
201 | <sect1><title>relay interface</title> | |
202 | !Ekernel/relay.c | |
203 | !Ikernel/relay.c | |
204 | </sect1> | |
205 | </chapter> | |
206 | ||
1da177e4 LT |
207 | <chapter id="netcore"> |
208 | <title>Linux Networking</title> | |
4dc3b16b PP |
209 | <sect1><title>Networking Base Types</title> |
210 | !Iinclude/linux/net.h | |
211 | </sect1> | |
1da177e4 LT |
212 | <sect1><title>Socket Buffer Functions</title> |
213 | !Iinclude/linux/skbuff.h | |
4dc3b16b PP |
214 | !Iinclude/net/sock.h |
215 | !Enet/socket.c | |
1da177e4 | 216 | !Enet/core/skbuff.c |
4dc3b16b PP |
217 | !Enet/core/sock.c |
218 | !Enet/core/datagram.c | |
219 | !Enet/core/stream.c | |
1da177e4 LT |
220 | </sect1> |
221 | <sect1><title>Socket Filter</title> | |
222 | !Enet/core/filter.c | |
223 | </sect1> | |
224 | <sect1><title>Generic Network Statistics</title> | |
225 | !Iinclude/linux/gen_stats.h | |
226 | !Enet/core/gen_stats.c | |
227 | !Enet/core/gen_estimator.c | |
228 | </sect1> | |
4dc3b16b PP |
229 | <sect1><title>SUN RPC subsystem</title> |
230 | <!-- The !D functionality is not perfect, garbage has to be protected by comments | |
231 | !Dnet/sunrpc/sunrpc_syms.c | |
232 | --> | |
233 | !Enet/sunrpc/xdr.c | |
65b6e42c RD |
234 | !Enet/sunrpc/svc_xprt.c |
235 | !Enet/sunrpc/xprt.c | |
4dc3b16b | 236 | !Enet/sunrpc/sched.c |
65b6e42c RD |
237 | !Enet/sunrpc/socklib.c |
238 | !Enet/sunrpc/stats.c | |
239 | !Enet/sunrpc/rpc_pipe.c | |
240 | !Enet/sunrpc/rpcb_clnt.c | |
241 | !Enet/sunrpc/clnt.c | |
4dc3b16b | 242 | </sect1> |
1da177e4 LT |
243 | </chapter> |
244 | ||
245 | <chapter id="netdev"> | |
246 | <title>Network device support</title> | |
247 | <sect1><title>Driver Support</title> | |
248 | !Enet/core/dev.c | |
c2da8aca | 249 | !Enet/ethernet/eth.c |
bea3348e | 250 | !Enet/sched/sch_generic.c |
461ddf3b | 251 | !Iinclude/linux/etherdevice.h |
bea3348e SH |
252 | !Iinclude/linux/netdevice.h |
253 | </sect1> | |
254 | <sect1><title>PHY Support</title> | |
b3df0da8 RD |
255 | !Edrivers/net/phy/phy.c |
256 | !Idrivers/net/phy/phy.c | |
257 | !Edrivers/net/phy/phy_device.c | |
258 | !Idrivers/net/phy/phy_device.c | |
259 | !Edrivers/net/phy/mdio_bus.c | |
260 | !Idrivers/net/phy/mdio_bus.c | |
bea3348e | 261 | </sect1> |
461ddf3b | 262 | <!-- FIXME: Removed for now since no structured comments in source |
bea3348e | 263 | <sect1><title>Wireless</title> |
461ddf3b | 264 | X!Enet/core/wireless.c |
1da177e4 | 265 | </sect1> |
bea3348e | 266 | --> |
1da177e4 LT |
267 | <sect1><title>Synchronous PPP</title> |
268 | !Edrivers/net/wan/syncppp.c | |
269 | </sect1> | |
270 | </chapter> | |
271 | ||
272 | <chapter id="modload"> | |
273 | <title>Module Support</title> | |
274 | <sect1><title>Module Loading</title> | |
275 | !Ekernel/kmod.c | |
276 | </sect1> | |
277 | <sect1><title>Inter Module support</title> | |
278 | <para> | |
279 | Refer to the file kernel/module.c for more information. | |
280 | </para> | |
281 | <!-- FIXME: Removed for now since no structured comments in source | |
282 | X!Ekernel/module.c | |
283 | --> | |
284 | </sect1> | |
285 | </chapter> | |
286 | ||
287 | <chapter id="hardware"> | |
288 | <title>Hardware Interfaces</title> | |
289 | <sect1><title>Interrupt Handling</title> | |
8f2709b5 | 290 | !Ekernel/irq/manage.c |
1da177e4 LT |
291 | </sect1> |
292 | ||
eed34d0f RD |
293 | <sect1><title>DMA Channels</title> |
294 | !Ekernel/dma.c | |
295 | </sect1> | |
296 | ||
4dc3b16b | 297 | <sect1><title>Resources Management</title> |
2b54960b | 298 | !Ikernel/resource.c |
e1ca66d1 | 299 | !Ekernel/resource.c |
4dc3b16b PP |
300 | </sect1> |
301 | ||
1da177e4 | 302 | <sect1><title>MTRR Handling</title> |
f3cf31ad | 303 | !Earch/x86/kernel/cpu/mtrr/main.c |
1da177e4 | 304 | </sect1> |
b0ef371e | 305 | |
1da177e4 LT |
306 | <sect1><title>PCI Support Library</title> |
307 | !Edrivers/pci/pci.c | |
4dc3b16b PP |
308 | !Edrivers/pci/pci-driver.c |
309 | !Edrivers/pci/remove.c | |
310 | !Edrivers/pci/pci-acpi.c | |
d75763d2 | 311 | !Edrivers/pci/search.c |
4dc3b16b PP |
312 | !Edrivers/pci/msi.c |
313 | !Edrivers/pci/bus.c | |
f05aab8e RD |
314 | <!-- FIXME: Removed for now since no structured comments in source |
315 | X!Edrivers/pci/hotplug.c | |
316 | --> | |
4dc3b16b PP |
317 | !Edrivers/pci/probe.c |
318 | !Edrivers/pci/rom.c | |
1da177e4 LT |
319 | </sect1> |
320 | <sect1><title>PCI Hotplug Support Library</title> | |
321 | !Edrivers/pci/hotplug/pci_hotplug_core.c | |
322 | </sect1> | |
323 | <sect1><title>MCA Architecture</title> | |
324 | <sect2><title>MCA Device Functions</title> | |
325 | <para> | |
f3cf31ad | 326 | Refer to the file arch/x86/kernel/mca_32.c for more information. |
1da177e4 LT |
327 | </para> |
328 | <!-- FIXME: Removed for now since no structured comments in source | |
f3cf31ad | 329 | X!Earch/x86/kernel/mca_32.c |
1da177e4 LT |
330 | --> |
331 | </sect2> | |
332 | <sect2><title>MCA Bus DMA</title> | |
f3cf31ad | 333 | !Iinclude/asm-x86/mca_dma.h |
1da177e4 LT |
334 | </sect2> |
335 | </sect1> | |
336 | </chapter> | |
337 | ||
b0ef371e RD |
338 | <chapter id="firmware"> |
339 | <title>Firmware Interfaces</title> | |
340 | <sect1><title>DMI Interfaces</title> | |
341 | !Edrivers/firmware/dmi_scan.c | |
342 | </sect1> | |
6e8c8188 RD |
343 | <sect1><title>EDD Interfaces</title> |
344 | !Idrivers/firmware/edd.c | |
345 | </sect1> | |
b0ef371e RD |
346 | </chapter> |
347 | ||
1da177e4 LT |
348 | <chapter id="security"> |
349 | <title>Security Framework</title> | |
20510f2f | 350 | !Isecurity/security.c |
1da177e4 LT |
351 | </chapter> |
352 | ||
862f5f01 RD |
353 | <chapter id="audit"> |
354 | <title>Audit Interfaces</title> | |
355 | !Ekernel/audit.c | |
356 | !Ikernel/auditsc.c | |
357 | !Ikernel/auditfilter.c | |
358 | </chapter> | |
359 | ||
360 | <chapter id="accounting"> | |
361 | <title>Accounting Framework</title> | |
362 | !Ikernel/acct.c | |
363 | </chapter> | |
364 | ||
1da177e4 LT |
365 | <chapter id="pmfuncs"> |
366 | <title>Power Management</title> | |
367 | !Ekernel/power/pm.c | |
368 | </chapter> | |
369 | ||
4dc3b16b PP |
370 | <chapter id="devdrivers"> |
371 | <title>Device drivers infrastructure</title> | |
372 | <sect1><title>Device Drivers Base</title> | |
373 | <!-- | |
374 | X!Iinclude/linux/device.h | |
375 | --> | |
376 | !Edrivers/base/driver.c | |
4dc3b16b | 377 | !Edrivers/base/core.c |
78b2290f | 378 | !Edrivers/base/class.c |
4dc3b16b PP |
379 | !Edrivers/base/firmware_class.c |
380 | !Edrivers/base/transport_class.c | |
4dc3b16b PP |
381 | <!-- Cannot be included, because |
382 | attribute_container_add_class_device_adapter | |
383 | and attribute_container_classdev_to_container | |
384 | exceed allowed 44 characters maximum | |
385 | X!Edrivers/base/attribute_container.c | |
386 | --> | |
387 | !Edrivers/base/sys.c | |
388 | <!-- | |
389 | X!Edrivers/base/interface.c | |
390 | --> | |
391 | !Edrivers/base/platform.c | |
392 | !Edrivers/base/bus.c | |
393 | </sect1> | |
394 | <sect1><title>Device Drivers Power Management</title> | |
3f51bed3 | 395 | !Edrivers/base/power/main.c |
4dc3b16b PP |
396 | </sect1> |
397 | <sect1><title>Device Drivers ACPI Support</title> | |
398 | <!-- Internal functions only | |
399 | X!Edrivers/acpi/sleep/main.c | |
400 | X!Edrivers/acpi/sleep/wakeup.c | |
401 | X!Edrivers/acpi/motherboard.c | |
402 | X!Edrivers/acpi/bus.c | |
403 | --> | |
404 | !Edrivers/acpi/scan.c | |
d758a8fa | 405 | !Idrivers/acpi/scan.c |
4dc3b16b PP |
406 | <!-- No correct structured comments |
407 | X!Edrivers/acpi/pci_bind.c | |
408 | --> | |
409 | </sect1> | |
410 | <sect1><title>Device drivers PnP support</title> | |
b8a36793 | 411 | !Idrivers/pnp/core.c |
4dc3b16b PP |
412 | <!-- No correct structured comments |
413 | X!Edrivers/pnp/system.c | |
414 | --> | |
415 | !Edrivers/pnp/card.c | |
b8a36793 | 416 | !Idrivers/pnp/driver.c |
4dc3b16b PP |
417 | !Edrivers/pnp/manager.c |
418 | !Edrivers/pnp/support.c | |
419 | </sect1> | |
e3e0a28b HK |
420 | <sect1><title>Userspace IO devices</title> |
421 | !Edrivers/uio/uio.c | |
422 | !Iinclude/linux/uio_driver.h | |
423 | </sect1> | |
4dc3b16b PP |
424 | </chapter> |
425 | ||
1da177e4 LT |
426 | <chapter id="blkdev"> |
427 | <title>Block Devices</title> | |
caf03feb RD |
428 | !Eblock/blk-core.c |
429 | !Eblock/blk-map.c | |
430 | !Iblock/blk-sysfs.c | |
431 | !Eblock/blk-settings.c | |
432 | !Eblock/blk-exec.c | |
433 | !Eblock/blk-barrier.c | |
434 | !Eblock/blk-tag.c | |
1da177e4 LT |
435 | </chapter> |
436 | ||
cf3e43db JC |
437 | <chapter id="chrdev"> |
438 | <title>Char devices</title> | |
439 | !Efs/char_dev.c | |
440 | </chapter> | |
441 | ||
1da177e4 LT |
442 | <chapter id="miscdev"> |
443 | <title>Miscellaneous Devices</title> | |
444 | !Edrivers/char/misc.c | |
445 | </chapter> | |
446 | ||
7d469722 RD |
447 | <chapter id="parportdev"> |
448 | <title>Parallel Port Devices</title> | |
449 | !Iinclude/linux/parport.h | |
450 | !Edrivers/parport/ieee1284.c | |
451 | !Edrivers/parport/share.c | |
452 | !Idrivers/parport/daisy.c | |
453 | </chapter> | |
454 | ||
da39aa8f RD |
455 | <chapter id="message_devices"> |
456 | <title>Message-based devices</title> | |
457 | <sect1><title>Fusion message devices</title> | |
458 | !Edrivers/message/fusion/mptbase.c | |
459 | !Idrivers/message/fusion/mptbase.c | |
460 | !Edrivers/message/fusion/mptscsih.c | |
461 | !Idrivers/message/fusion/mptscsih.c | |
462 | !Idrivers/message/fusion/mptctl.c | |
463 | !Idrivers/message/fusion/mptspi.c | |
464 | !Idrivers/message/fusion/mptfc.c | |
465 | !Idrivers/message/fusion/mptlan.c | |
466 | </sect1> | |
467 | <sect1><title>I2O message devices</title> | |
468 | !Iinclude/linux/i2o.h | |
469 | !Idrivers/message/i2o/core.h | |
470 | !Edrivers/message/i2o/iop.c | |
471 | !Idrivers/message/i2o/iop.c | |
472 | !Idrivers/message/i2o/config-osm.c | |
473 | !Edrivers/message/i2o/exec-osm.c | |
474 | !Idrivers/message/i2o/exec-osm.c | |
475 | !Idrivers/message/i2o/bus-osm.c | |
476 | !Edrivers/message/i2o/device.c | |
477 | !Idrivers/message/i2o/device.c | |
478 | !Idrivers/message/i2o/driver.c | |
479 | !Idrivers/message/i2o/pci.c | |
480 | !Idrivers/message/i2o/i2o_block.c | |
481 | !Idrivers/message/i2o/i2o_scsi.c | |
482 | !Idrivers/message/i2o/i2o_proc.c | |
483 | </sect1> | |
1da177e4 LT |
484 | </chapter> |
485 | ||
486 | <chapter id="snddev"> | |
487 | <title>Sound Devices</title> | |
4dc3b16b | 488 | !Iinclude/sound/core.h |
1da177e4 | 489 | !Esound/sound_core.c |
4dc3b16b PP |
490 | !Iinclude/sound/pcm.h |
491 | !Esound/core/pcm.c | |
492 | !Esound/core/device.c | |
493 | !Esound/core/info.c | |
494 | !Esound/core/rawmidi.c | |
495 | !Esound/core/sound.c | |
496 | !Esound/core/memory.c | |
497 | !Esound/core/pcm_memory.c | |
498 | !Esound/core/init.c | |
499 | !Esound/core/isadma.c | |
500 | !Esound/core/control.c | |
501 | !Esound/core/pcm_lib.c | |
502 | !Esound/core/hwdep.c | |
503 | !Esound/core/pcm_native.c | |
504 | !Esound/core/memalloc.c | |
1da177e4 LT |
505 | <!-- FIXME: Removed for now since no structured comments in source |
506 | X!Isound/sound_firmware.c | |
507 | --> | |
508 | </chapter> | |
509 | ||
510 | <chapter id="uart16x50"> | |
511 | <title>16x50 UART Driver</title> | |
4dc3b16b | 512 | !Iinclude/linux/serial_core.h |
1da177e4 LT |
513 | !Edrivers/serial/serial_core.c |
514 | !Edrivers/serial/8250.c | |
515 | </chapter> | |
516 | ||
517 | <chapter id="z85230"> | |
518 | <title>Z85230 Support Library</title> | |
519 | !Edrivers/net/wan/z85230.c | |
520 | </chapter> | |
521 | ||
522 | <chapter id="fbdev"> | |
523 | <title>Frame Buffer Library</title> | |
524 | ||
525 | <para> | |
526 | The frame buffer drivers depend heavily on four data structures. | |
527 | These structures are declared in include/linux/fb.h. They are | |
528 | fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. | |
529 | The last three can be made available to and from userland. | |
530 | </para> | |
531 | ||
532 | <para> | |
533 | fb_info defines the current state of a particular video card. | |
534 | Inside fb_info, there exists a fb_ops structure which is a | |
535 | collection of needed functions to make fbdev and fbcon work. | |
536 | fb_info is only visible to the kernel. | |
537 | </para> | |
538 | ||
539 | <para> | |
540 | fb_var_screeninfo is used to describe the features of a video card | |
541 | that are user defined. With fb_var_screeninfo, things such as | |
542 | depth and the resolution may be defined. | |
543 | </para> | |
544 | ||
545 | <para> | |
546 | The next structure is fb_fix_screeninfo. This defines the | |
547 | properties of a card that are created when a mode is set and can't | |
548 | be changed otherwise. A good example of this is the start of the | |
549 | frame buffer memory. This "locks" the address of the frame buffer | |
550 | memory, so that it cannot be changed or moved. | |
551 | </para> | |
552 | ||
553 | <para> | |
554 | The last structure is fb_monospecs. In the old API, there was | |
555 | little importance for fb_monospecs. This allowed for forbidden things | |
556 | such as setting a mode of 800x600 on a fix frequency monitor. With | |
557 | the new API, fb_monospecs prevents such things, and if used | |
558 | correctly, can prevent a monitor from being cooked. fb_monospecs | |
559 | will not be useful until kernels 2.5.x. | |
560 | </para> | |
561 | ||
562 | <sect1><title>Frame Buffer Memory</title> | |
563 | !Edrivers/video/fbmem.c | |
564 | </sect1> | |
4dc3b16b | 565 | <!-- |
1da177e4 | 566 | <sect1><title>Frame Buffer Console</title> |
4dc3b16b | 567 | X!Edrivers/video/console/fbcon.c |
1da177e4 | 568 | </sect1> |
4dc3b16b | 569 | --> |
1da177e4 LT |
570 | <sect1><title>Frame Buffer Colormap</title> |
571 | !Edrivers/video/fbcmap.c | |
572 | </sect1> | |
573 | <!-- FIXME: | |
574 | drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment | |
575 | out until somebody adds docs. KAO | |
576 | <sect1><title>Frame Buffer Generic Functions</title> | |
577 | X!Idrivers/video/fbgen.c | |
578 | </sect1> | |
579 | KAO --> | |
580 | <sect1><title>Frame Buffer Video Mode Database</title> | |
581 | !Idrivers/video/modedb.c | |
582 | !Edrivers/video/modedb.c | |
583 | </sect1> | |
584 | <sect1><title>Frame Buffer Macintosh Video Mode Database</title> | |
8f2709b5 | 585 | !Edrivers/video/macmodes.c |
1da177e4 LT |
586 | </sect1> |
587 | <sect1><title>Frame Buffer Fonts</title> | |
588 | <para> | |
589 | Refer to the file drivers/video/console/fonts.c for more information. | |
590 | </para> | |
591 | <!-- FIXME: Removed for now since no structured comments in source | |
592 | X!Idrivers/video/console/fonts.c | |
593 | --> | |
594 | </sect1> | |
595 | </chapter> | |
e4477d2d RD |
596 | |
597 | <chapter id="input_subsystem"> | |
598 | <title>Input Subsystem</title> | |
599 | !Iinclude/linux/input.h | |
600 | !Edrivers/input/input.c | |
601 | !Edrivers/input/ff-core.c | |
602 | !Edrivers/input/ff-memless.c | |
603 | </chapter> | |
33e34dc6 DB |
604 | |
605 | <chapter id="spi"> | |
606 | <title>Serial Peripheral Interface (SPI)</title> | |
607 | <para> | |
608 | SPI is the "Serial Peripheral Interface", widely used with | |
609 | embedded systems because it is a simple and efficient | |
610 | interface: basically a multiplexed shift register. | |
611 | Its three signal wires hold a clock (SCK, often in the range | |
612 | of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and | |
613 | a "Master In, Slave Out" (MISO) data line. | |
614 | SPI is a full duplex protocol; for each bit shifted out the | |
615 | MOSI line (one per clock) another is shifted in on the MISO line. | |
616 | Those bits are assembled into words of various sizes on the | |
617 | way to and from system memory. | |
618 | An additional chipselect line is usually active-low (nCS); | |
619 | four signals are normally used for each peripheral, plus | |
620 | sometimes an interrupt. | |
621 | </para> | |
622 | <para> | |
623 | The SPI bus facilities listed here provide a generalized | |
624 | interface to declare SPI busses and devices, manage them | |
625 | according to the standard Linux driver model, and perform | |
626 | input/output operations. | |
627 | At this time, only "master" side interfaces are supported, | |
628 | where Linux talks to SPI peripherals and does not implement | |
629 | such a peripheral itself. | |
630 | (Interfaces to support implementing SPI slaves would | |
631 | necessarily look different.) | |
632 | </para> | |
633 | <para> | |
634 | The programming interface is structured around two kinds of driver, | |
635 | and two kinds of device. | |
636 | A "Controller Driver" abstracts the controller hardware, which may | |
637 | be as simple as a set of GPIO pins or as complex as a pair of FIFOs | |
638 | connected to dual DMA engines on the other side of the SPI shift | |
639 | register (maximizing throughput). Such drivers bridge between | |
640 | whatever bus they sit on (often the platform bus) and SPI, and | |
641 | expose the SPI side of their device as a | |
642 | <structname>struct spi_master</structname>. | |
643 | SPI devices are children of that master, represented as a | |
644 | <structname>struct spi_device</structname> and manufactured from | |
645 | <structname>struct spi_board_info</structname> descriptors which | |
646 | are usually provided by board-specific initialization code. | |
647 | A <structname>struct spi_driver</structname> is called a | |
648 | "Protocol Driver", and is bound to a spi_device using normal | |
649 | driver model calls. | |
650 | </para> | |
651 | <para> | |
652 | The I/O model is a set of queued messages. Protocol drivers | |
653 | submit one or more <structname>struct spi_message</structname> | |
654 | objects, which are processed and completed asynchronously. | |
655 | (There are synchronous wrappers, however.) Messages are | |
656 | built from one or more <structname>struct spi_transfer</structname> | |
657 | objects, each of which wraps a full duplex SPI transfer. | |
658 | A variety of protocol tweaking options are needed, because | |
659 | different chips adopt very different policies for how they | |
660 | use the bits transferred with SPI. | |
661 | </para> | |
662 | !Iinclude/linux/spi/spi.h | |
663 | !Fdrivers/spi/spi.c spi_register_board_info | |
664 | !Edrivers/spi/spi.c | |
665 | </chapter> | |
666 | ||
d64f73be DB |
667 | <chapter id="i2c"> |
668 | <title>I<superscript>2</superscript>C and SMBus Subsystem</title> | |
669 | ||
670 | <para> | |
671 | I<superscript>2</superscript>C (or without fancy typography, "I2C") | |
672 | is an acronym for the "Inter-IC" bus, a simple bus protocol which is | |
673 | widely used where low data rate communications suffice. | |
674 | Since it's also a licensed trademark, some vendors use another | |
675 | name (such as "Two-Wire Interface", TWI) for the same bus. | |
676 | I2C only needs two signals (SCL for clock, SDA for data), conserving | |
677 | board real estate and minimizing signal quality issues. | |
678 | Most I2C devices use seven bit addresses, and bus speeds of up | |
679 | to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet | |
680 | found wide use. | |
681 | I2C is a multi-master bus; open drain signaling is used to | |
682 | arbitrate between masters, as well as to handshake and to | |
683 | synchronize clocks from slower clients. | |
684 | </para> | |
685 | ||
686 | <para> | |
687 | The Linux I2C programming interfaces support only the master | |
688 | side of bus interactions, not the slave side. | |
689 | The programming interface is structured around two kinds of driver, | |
690 | and two kinds of device. | |
691 | An I2C "Adapter Driver" abstracts the controller hardware; it binds | |
692 | to a physical device (perhaps a PCI device or platform_device) and | |
693 | exposes a <structname>struct i2c_adapter</structname> representing | |
694 | each I2C bus segment it manages. | |
695 | On each I2C bus segment will be I2C devices represented by a | |
696 | <structname>struct i2c_client</structname>. Those devices will | |
697 | be bound to a <structname>struct i2c_driver</structname>, | |
698 | which should follow the standard Linux driver model. | |
699 | (At this writing, a legacy model is more widely used.) | |
700 | There are functions to perform various I2C protocol operations; at | |
701 | this writing all such functions are usable only from task context. | |
702 | </para> | |
703 | ||
704 | <para> | |
705 | The System Management Bus (SMBus) is a sibling protocol. Most SMBus | |
706 | systems are also I2C conformant. The electrical constraints are | |
707 | tighter for SMBus, and it standardizes particular protocol messages | |
708 | and idioms. Controllers that support I2C can also support most | |
709 | SMBus operations, but SMBus controllers don't support all the protocol | |
710 | options that an I2C controller will. | |
711 | There are functions to perform various SMBus protocol operations, | |
712 | either using I2C primitives or by issuing SMBus commands to | |
713 | i2c_adapter devices which don't support those I2C operations. | |
714 | </para> | |
715 | ||
716 | !Iinclude/linux/i2c.h | |
717 | !Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info | |
718 | !Edrivers/i2c/i2c-core.c | |
719 | </chapter> | |
720 | ||
1da177e4 | 721 | </book> |