Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docbook: split kernel-api for device-drivers
The kernel-api docbook was much larger than any of the others,
so processing it took longer and needed some docbook extras in
some cases, so split it into kernel-api (infrastructure etc.)
and device drivers/device subsystems. This allows these docbooks
to be generated in parallel. (This reduced the docbook processing
time on my 4-proc system with make -j4 from about 5min:16sec to
about 2min:01sec.)
The chapters that were moved from kernel-api to device-drivers are:
Driver Basics
Device drivers infrastructure
Parallel Port Devices
Message-based devices
Sound Devices
16x50 UART Driver
Frame Buffer Library
Input Subsystem
Serial Peripheral Interface (SPI)
I2C and SMBus Subsystem
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
authored by
Randy Dunlap
and committed by
Linus Torvalds
f7f84f38
770824bd
+419
-378
+1
-1
Documentation/DocBook/Makefile
+1
-1
Documentation/DocBook/Makefile
···
6
6
# To add a new book the only step required is to add the book to the
7
7
# list of DOCBOOKS.
8
8
9
-
DOCBOOKS := z8530book.xml mcabook.xml \
9
+
DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
10
10
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11
11
procfs-guide.xml writing_usb_driver.xml networking.xml \
12
12
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
+418
Documentation/DocBook/device-drivers.tmpl
+418
Documentation/DocBook/device-drivers.tmpl
···
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="LinuxDriversAPI">
6
+
<bookinfo>
7
+
<title>Linux Device Drivers</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
+
!Iarch/x86/include/asm/atomic_32.h
49
+
!Iarch/x86/include/asm/unaligned.h
50
+
</sect1>
51
+
52
+
<sect1><title>Delaying, scheduling, and timer routines</title>
53
+
!Iinclude/linux/sched.h
54
+
!Ekernel/sched.c
55
+
!Ekernel/timer.c
56
+
</sect1>
57
+
<sect1><title>High-resolution timers</title>
58
+
!Iinclude/linux/ktime.h
59
+
!Iinclude/linux/hrtimer.h
60
+
!Ekernel/hrtimer.c
61
+
</sect1>
62
+
<sect1><title>Workqueues and Kevents</title>
63
+
!Ekernel/workqueue.c
64
+
</sect1>
65
+
<sect1><title>Internal Functions</title>
66
+
!Ikernel/exit.c
67
+
!Ikernel/signal.c
68
+
!Iinclude/linux/kthread.h
69
+
!Ekernel/kthread.c
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
81
+
!Ekernel/printk.c
82
+
!Ekernel/panic.c
83
+
!Ekernel/sys.c
84
+
!Ekernel/rcupdate.c
85
+
</sect1>
86
+
87
+
<sect1><title>Device Resource Management</title>
88
+
!Edrivers/base/devres.c
89
+
</sect1>
90
+
91
+
</chapter>
92
+
93
+
<chapter id="devdrivers">
94
+
<title>Device drivers infrastructure</title>
95
+
<sect1><title>Device Drivers Base</title>
96
+
<!--
97
+
X!Iinclude/linux/device.h
98
+
-->
99
+
!Edrivers/base/driver.c
100
+
!Edrivers/base/core.c
101
+
!Edrivers/base/class.c
102
+
!Edrivers/base/firmware_class.c
103
+
!Edrivers/base/transport_class.c
104
+
<!-- Cannot be included, because
105
+
attribute_container_add_class_device_adapter
106
+
and attribute_container_classdev_to_container
107
+
exceed allowed 44 characters maximum
108
+
X!Edrivers/base/attribute_container.c
109
+
-->
110
+
!Edrivers/base/sys.c
111
+
<!--
112
+
X!Edrivers/base/interface.c
113
+
-->
114
+
!Edrivers/base/platform.c
115
+
!Edrivers/base/bus.c
116
+
</sect1>
117
+
<sect1><title>Device Drivers Power Management</title>
118
+
!Edrivers/base/power/main.c
119
+
</sect1>
120
+
<sect1><title>Device Drivers ACPI Support</title>
121
+
<!-- Internal functions only
122
+
X!Edrivers/acpi/sleep/main.c
123
+
X!Edrivers/acpi/sleep/wakeup.c
124
+
X!Edrivers/acpi/motherboard.c
125
+
X!Edrivers/acpi/bus.c
126
+
-->
127
+
!Edrivers/acpi/scan.c
128
+
!Idrivers/acpi/scan.c
129
+
<!-- No correct structured comments
130
+
X!Edrivers/acpi/pci_bind.c
131
+
-->
132
+
</sect1>
133
+
<sect1><title>Device drivers PnP support</title>
134
+
!Idrivers/pnp/core.c
135
+
<!-- No correct structured comments
136
+
X!Edrivers/pnp/system.c
137
+
-->
138
+
!Edrivers/pnp/card.c
139
+
!Idrivers/pnp/driver.c
140
+
!Edrivers/pnp/manager.c
141
+
!Edrivers/pnp/support.c
142
+
</sect1>
143
+
<sect1><title>Userspace IO devices</title>
144
+
!Edrivers/uio/uio.c
145
+
!Iinclude/linux/uio_driver.h
146
+
</sect1>
147
+
</chapter>
148
+
149
+
<chapter id="parportdev">
150
+
<title>Parallel Port Devices</title>
151
+
!Iinclude/linux/parport.h
152
+
!Edrivers/parport/ieee1284.c
153
+
!Edrivers/parport/share.c
154
+
!Idrivers/parport/daisy.c
155
+
</chapter>
156
+
157
+
<chapter id="message_devices">
158
+
<title>Message-based devices</title>
159
+
<sect1><title>Fusion message devices</title>
160
+
!Edrivers/message/fusion/mptbase.c
161
+
!Idrivers/message/fusion/mptbase.c
162
+
!Edrivers/message/fusion/mptscsih.c
163
+
!Idrivers/message/fusion/mptscsih.c
164
+
!Idrivers/message/fusion/mptctl.c
165
+
!Idrivers/message/fusion/mptspi.c
166
+
!Idrivers/message/fusion/mptfc.c
167
+
!Idrivers/message/fusion/mptlan.c
168
+
</sect1>
169
+
<sect1><title>I2O message devices</title>
170
+
!Iinclude/linux/i2o.h
171
+
!Idrivers/message/i2o/core.h
172
+
!Edrivers/message/i2o/iop.c
173
+
!Idrivers/message/i2o/iop.c
174
+
!Idrivers/message/i2o/config-osm.c
175
+
!Edrivers/message/i2o/exec-osm.c
176
+
!Idrivers/message/i2o/exec-osm.c
177
+
!Idrivers/message/i2o/bus-osm.c
178
+
!Edrivers/message/i2o/device.c
179
+
!Idrivers/message/i2o/device.c
180
+
!Idrivers/message/i2o/driver.c
181
+
!Idrivers/message/i2o/pci.c
182
+
!Idrivers/message/i2o/i2o_block.c
183
+
!Idrivers/message/i2o/i2o_scsi.c
184
+
!Idrivers/message/i2o/i2o_proc.c
185
+
</sect1>
186
+
</chapter>
187
+
188
+
<chapter id="snddev">
189
+
<title>Sound Devices</title>
190
+
!Iinclude/sound/core.h
191
+
!Esound/sound_core.c
192
+
!Iinclude/sound/pcm.h
193
+
!Esound/core/pcm.c
194
+
!Esound/core/device.c
195
+
!Esound/core/info.c
196
+
!Esound/core/rawmidi.c
197
+
!Esound/core/sound.c
198
+
!Esound/core/memory.c
199
+
!Esound/core/pcm_memory.c
200
+
!Esound/core/init.c
201
+
!Esound/core/isadma.c
202
+
!Esound/core/control.c
203
+
!Esound/core/pcm_lib.c
204
+
!Esound/core/hwdep.c
205
+
!Esound/core/pcm_native.c
206
+
!Esound/core/memalloc.c
207
+
<!-- FIXME: Removed for now since no structured comments in source
208
+
X!Isound/sound_firmware.c
209
+
-->
210
+
</chapter>
211
+
212
+
<chapter id="uart16x50">
213
+
<title>16x50 UART Driver</title>
214
+
!Iinclude/linux/serial_core.h
215
+
!Edrivers/serial/serial_core.c
216
+
!Edrivers/serial/8250.c
217
+
</chapter>
218
+
219
+
<chapter id="fbdev">
220
+
<title>Frame Buffer Library</title>
221
+
222
+
<para>
223
+
The frame buffer drivers depend heavily on four data structures.
224
+
These structures are declared in include/linux/fb.h. They are
225
+
fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
226
+
The last three can be made available to and from userland.
227
+
</para>
228
+
229
+
<para>
230
+
fb_info defines the current state of a particular video card.
231
+
Inside fb_info, there exists a fb_ops structure which is a
232
+
collection of needed functions to make fbdev and fbcon work.
233
+
fb_info is only visible to the kernel.
234
+
</para>
235
+
236
+
<para>
237
+
fb_var_screeninfo is used to describe the features of a video card
238
+
that are user defined. With fb_var_screeninfo, things such as
239
+
depth and the resolution may be defined.
240
+
</para>
241
+
242
+
<para>
243
+
The next structure is fb_fix_screeninfo. This defines the
244
+
properties of a card that are created when a mode is set and can't
245
+
be changed otherwise. A good example of this is the start of the
246
+
frame buffer memory. This "locks" the address of the frame buffer
247
+
memory, so that it cannot be changed or moved.
248
+
</para>
249
+
250
+
<para>
251
+
The last structure is fb_monospecs. In the old API, there was
252
+
little importance for fb_monospecs. This allowed for forbidden things
253
+
such as setting a mode of 800x600 on a fix frequency monitor. With
254
+
the new API, fb_monospecs prevents such things, and if used
255
+
correctly, can prevent a monitor from being cooked. fb_monospecs
256
+
will not be useful until kernels 2.5.x.
257
+
</para>
258
+
259
+
<sect1><title>Frame Buffer Memory</title>
260
+
!Edrivers/video/fbmem.c
261
+
</sect1>
262
+
<!--
263
+
<sect1><title>Frame Buffer Console</title>
264
+
X!Edrivers/video/console/fbcon.c
265
+
</sect1>
266
+
-->
267
+
<sect1><title>Frame Buffer Colormap</title>
268
+
!Edrivers/video/fbcmap.c
269
+
</sect1>
270
+
<!-- FIXME:
271
+
drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
272
+
out until somebody adds docs. KAO
273
+
<sect1><title>Frame Buffer Generic Functions</title>
274
+
X!Idrivers/video/fbgen.c
275
+
</sect1>
276
+
KAO -->
277
+
<sect1><title>Frame Buffer Video Mode Database</title>
278
+
!Idrivers/video/modedb.c
279
+
!Edrivers/video/modedb.c
280
+
</sect1>
281
+
<sect1><title>Frame Buffer Macintosh Video Mode Database</title>
282
+
!Edrivers/video/macmodes.c
283
+
</sect1>
284
+
<sect1><title>Frame Buffer Fonts</title>
285
+
<para>
286
+
Refer to the file drivers/video/console/fonts.c for more information.
287
+
</para>
288
+
<!-- FIXME: Removed for now since no structured comments in source
289
+
X!Idrivers/video/console/fonts.c
290
+
-->
291
+
</sect1>
292
+
</chapter>
293
+
294
+
<chapter id="input_subsystem">
295
+
<title>Input Subsystem</title>
296
+
!Iinclude/linux/input.h
297
+
!Edrivers/input/input.c
298
+
!Edrivers/input/ff-core.c
299
+
!Edrivers/input/ff-memless.c
300
+
</chapter>
301
+
302
+
<chapter id="spi">
303
+
<title>Serial Peripheral Interface (SPI)</title>
304
+
<para>
305
+
SPI is the "Serial Peripheral Interface", widely used with
306
+
embedded systems because it is a simple and efficient
307
+
interface: basically a multiplexed shift register.
308
+
Its three signal wires hold a clock (SCK, often in the range
309
+
of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
310
+
a "Master In, Slave Out" (MISO) data line.
311
+
SPI is a full duplex protocol; for each bit shifted out the
312
+
MOSI line (one per clock) another is shifted in on the MISO line.
313
+
Those bits are assembled into words of various sizes on the
314
+
way to and from system memory.
315
+
An additional chipselect line is usually active-low (nCS);
316
+
four signals are normally used for each peripheral, plus
317
+
sometimes an interrupt.
318
+
</para>
319
+
<para>
320
+
The SPI bus facilities listed here provide a generalized
321
+
interface to declare SPI busses and devices, manage them
322
+
according to the standard Linux driver model, and perform
323
+
input/output operations.
324
+
At this time, only "master" side interfaces are supported,
325
+
where Linux talks to SPI peripherals and does not implement
326
+
such a peripheral itself.
327
+
(Interfaces to support implementing SPI slaves would
328
+
necessarily look different.)
329
+
</para>
330
+
<para>
331
+
The programming interface is structured around two kinds of driver,
332
+
and two kinds of device.
333
+
A "Controller Driver" abstracts the controller hardware, which may
334
+
be as simple as a set of GPIO pins or as complex as a pair of FIFOs
335
+
connected to dual DMA engines on the other side of the SPI shift
336
+
register (maximizing throughput). Such drivers bridge between
337
+
whatever bus they sit on (often the platform bus) and SPI, and
338
+
expose the SPI side of their device as a
339
+
<structname>struct spi_master</structname>.
340
+
SPI devices are children of that master, represented as a
341
+
<structname>struct spi_device</structname> and manufactured from
342
+
<structname>struct spi_board_info</structname> descriptors which
343
+
are usually provided by board-specific initialization code.
344
+
A <structname>struct spi_driver</structname> is called a
345
+
"Protocol Driver", and is bound to a spi_device using normal
346
+
driver model calls.
347
+
</para>
348
+
<para>
349
+
The I/O model is a set of queued messages. Protocol drivers
350
+
submit one or more <structname>struct spi_message</structname>
351
+
objects, which are processed and completed asynchronously.
352
+
(There are synchronous wrappers, however.) Messages are
353
+
built from one or more <structname>struct spi_transfer</structname>
354
+
objects, each of which wraps a full duplex SPI transfer.
355
+
A variety of protocol tweaking options are needed, because
356
+
different chips adopt very different policies for how they
357
+
use the bits transferred with SPI.
358
+
</para>
359
+
!Iinclude/linux/spi/spi.h
360
+
!Fdrivers/spi/spi.c spi_register_board_info
361
+
!Edrivers/spi/spi.c
362
+
</chapter>
363
+
364
+
<chapter id="i2c">
365
+
<title>I<superscript>2</superscript>C and SMBus Subsystem</title>
366
+
367
+
<para>
368
+
I<superscript>2</superscript>C (or without fancy typography, "I2C")
369
+
is an acronym for the "Inter-IC" bus, a simple bus protocol which is
370
+
widely used where low data rate communications suffice.
371
+
Since it's also a licensed trademark, some vendors use another
372
+
name (such as "Two-Wire Interface", TWI) for the same bus.
373
+
I2C only needs two signals (SCL for clock, SDA for data), conserving
374
+
board real estate and minimizing signal quality issues.
375
+
Most I2C devices use seven bit addresses, and bus speeds of up
376
+
to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
377
+
found wide use.
378
+
I2C is a multi-master bus; open drain signaling is used to
379
+
arbitrate between masters, as well as to handshake and to
380
+
synchronize clocks from slower clients.
381
+
</para>
382
+
383
+
<para>
384
+
The Linux I2C programming interfaces support only the master
385
+
side of bus interactions, not the slave side.
386
+
The programming interface is structured around two kinds of driver,
387
+
and two kinds of device.
388
+
An I2C "Adapter Driver" abstracts the controller hardware; it binds
389
+
to a physical device (perhaps a PCI device or platform_device) and
390
+
exposes a <structname>struct i2c_adapter</structname> representing
391
+
each I2C bus segment it manages.
392
+
On each I2C bus segment will be I2C devices represented by a
393
+
<structname>struct i2c_client</structname>. Those devices will
394
+
be bound to a <structname>struct i2c_driver</structname>,
395
+
which should follow the standard Linux driver model.
396
+
(At this writing, a legacy model is more widely used.)
397
+
There are functions to perform various I2C protocol operations; at
398
+
this writing all such functions are usable only from task context.
399
+
</para>
400
+
401
+
<para>
402
+
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
403
+
systems are also I2C conformant. The electrical constraints are
404
+
tighter for SMBus, and it standardizes particular protocol messages
405
+
and idioms. Controllers that support I2C can also support most
406
+
SMBus operations, but SMBus controllers don't support all the protocol
407
+
options that an I2C controller will.
408
+
There are functions to perform various SMBus protocol operations,
409
+
either using I2C primitives or by issuing SMBus commands to
410
+
i2c_adapter devices which don't support those I2C operations.
411
+
</para>
412
+
413
+
!Iinclude/linux/i2c.h
414
+
!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
415
+
!Edrivers/i2c/i2c-core.c
416
+
</chapter>
417
+
418
+
</book>
-377
Documentation/DocBook/kernel-api.tmpl
-377
Documentation/DocBook/kernel-api.tmpl
···
38
38
39
39
<toc></toc>
40
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
-
!Iarch/x86/include/asm/atomic_32.h
49
-
!Iarch/x86/include/asm/unaligned.h
50
-
</sect1>
51
-
52
-
<sect1><title>Delaying, scheduling, and timer routines</title>
53
-
!Iinclude/linux/sched.h
54
-
!Ekernel/sched.c
55
-
!Ekernel/timer.c
56
-
</sect1>
57
-
<sect1><title>High-resolution timers</title>
58
-
!Iinclude/linux/ktime.h
59
-
!Iinclude/linux/hrtimer.h
60
-
!Ekernel/hrtimer.c
61
-
</sect1>
62
-
<sect1><title>Workqueues and Kevents</title>
63
-
!Ekernel/workqueue.c
64
-
</sect1>
65
-
<sect1><title>Internal Functions</title>
66
-
!Ikernel/exit.c
67
-
!Ikernel/signal.c
68
-
!Iinclude/linux/kthread.h
69
-
!Ekernel/kthread.c
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
81
-
!Ekernel/printk.c
82
-
!Ekernel/panic.c
83
-
!Ekernel/sys.c
84
-
!Ekernel/rcupdate.c
85
-
</sect1>
86
-
87
-
<sect1><title>Device Resource Management</title>
88
-
!Edrivers/base/devres.c
89
-
</sect1>
90
-
91
-
</chapter>
92
-
93
41
<chapter id="adt">
94
42
<title>Data Types</title>
95
43
<sect1><title>Doubly Linked Lists</title>
···
246
298
!Ikernel/acct.c
247
299
</chapter>
248
300
249
-
<chapter id="devdrivers">
250
-
<title>Device drivers infrastructure</title>
251
-
<sect1><title>Device Drivers Base</title>
252
-
<!--
253
-
X!Iinclude/linux/device.h
254
-
-->
255
-
!Edrivers/base/driver.c
256
-
!Edrivers/base/core.c
257
-
!Edrivers/base/class.c
258
-
!Edrivers/base/firmware_class.c
259
-
!Edrivers/base/transport_class.c
260
-
<!-- Cannot be included, because
261
-
attribute_container_add_class_device_adapter
262
-
and attribute_container_classdev_to_container
263
-
exceed allowed 44 characters maximum
264
-
X!Edrivers/base/attribute_container.c
265
-
-->
266
-
!Edrivers/base/sys.c
267
-
<!--
268
-
X!Edrivers/base/interface.c
269
-
-->
270
-
!Edrivers/base/platform.c
271
-
!Edrivers/base/bus.c
272
-
</sect1>
273
-
<sect1><title>Device Drivers Power Management</title>
274
-
!Edrivers/base/power/main.c
275
-
</sect1>
276
-
<sect1><title>Device Drivers ACPI Support</title>
277
-
<!-- Internal functions only
278
-
X!Edrivers/acpi/sleep/main.c
279
-
X!Edrivers/acpi/sleep/wakeup.c
280
-
X!Edrivers/acpi/motherboard.c
281
-
X!Edrivers/acpi/bus.c
282
-
-->
283
-
!Edrivers/acpi/scan.c
284
-
!Idrivers/acpi/scan.c
285
-
<!-- No correct structured comments
286
-
X!Edrivers/acpi/pci_bind.c
287
-
-->
288
-
</sect1>
289
-
<sect1><title>Device drivers PnP support</title>
290
-
!Idrivers/pnp/core.c
291
-
<!-- No correct structured comments
292
-
X!Edrivers/pnp/system.c
293
-
-->
294
-
!Edrivers/pnp/card.c
295
-
!Idrivers/pnp/driver.c
296
-
!Edrivers/pnp/manager.c
297
-
!Edrivers/pnp/support.c
298
-
</sect1>
299
-
<sect1><title>Userspace IO devices</title>
300
-
!Edrivers/uio/uio.c
301
-
!Iinclude/linux/uio_driver.h
302
-
</sect1>
303
-
</chapter>
304
-
305
301
<chapter id="blkdev">
306
302
<title>Block Devices</title>
307
303
!Eblock/blk-core.c
···
271
379
<chapter id="miscdev">
272
380
<title>Miscellaneous Devices</title>
273
381
!Edrivers/char/misc.c
274
-
</chapter>
275
-
276
-
<chapter id="parportdev">
277
-
<title>Parallel Port Devices</title>
278
-
!Iinclude/linux/parport.h
279
-
!Edrivers/parport/ieee1284.c
280
-
!Edrivers/parport/share.c
281
-
!Idrivers/parport/daisy.c
282
-
</chapter>
283
-
284
-
<chapter id="message_devices">
285
-
<title>Message-based devices</title>
286
-
<sect1><title>Fusion message devices</title>
287
-
!Edrivers/message/fusion/mptbase.c
288
-
!Idrivers/message/fusion/mptbase.c
289
-
!Edrivers/message/fusion/mptscsih.c
290
-
!Idrivers/message/fusion/mptscsih.c
291
-
!Idrivers/message/fusion/mptctl.c
292
-
!Idrivers/message/fusion/mptspi.c
293
-
!Idrivers/message/fusion/mptfc.c
294
-
!Idrivers/message/fusion/mptlan.c
295
-
</sect1>
296
-
<sect1><title>I2O message devices</title>
297
-
!Iinclude/linux/i2o.h
298
-
!Idrivers/message/i2o/core.h
299
-
!Edrivers/message/i2o/iop.c
300
-
!Idrivers/message/i2o/iop.c
301
-
!Idrivers/message/i2o/config-osm.c
302
-
!Edrivers/message/i2o/exec-osm.c
303
-
!Idrivers/message/i2o/exec-osm.c
304
-
!Idrivers/message/i2o/bus-osm.c
305
-
!Edrivers/message/i2o/device.c
306
-
!Idrivers/message/i2o/device.c
307
-
!Idrivers/message/i2o/driver.c
308
-
!Idrivers/message/i2o/pci.c
309
-
!Idrivers/message/i2o/i2o_block.c
310
-
!Idrivers/message/i2o/i2o_scsi.c
311
-
!Idrivers/message/i2o/i2o_proc.c
312
-
</sect1>
313
-
</chapter>
314
-
315
-
<chapter id="snddev">
316
-
<title>Sound Devices</title>
317
-
!Iinclude/sound/core.h
318
-
!Esound/sound_core.c
319
-
!Iinclude/sound/pcm.h
320
-
!Esound/core/pcm.c
321
-
!Esound/core/device.c
322
-
!Esound/core/info.c
323
-
!Esound/core/rawmidi.c
324
-
!Esound/core/sound.c
325
-
!Esound/core/memory.c
326
-
!Esound/core/pcm_memory.c
327
-
!Esound/core/init.c
328
-
!Esound/core/isadma.c
329
-
!Esound/core/control.c
330
-
!Esound/core/pcm_lib.c
331
-
!Esound/core/hwdep.c
332
-
!Esound/core/pcm_native.c
333
-
!Esound/core/memalloc.c
334
-
<!-- FIXME: Removed for now since no structured comments in source
335
-
X!Isound/sound_firmware.c
336
-
-->
337
-
</chapter>
338
-
339
-
<chapter id="uart16x50">
340
-
<title>16x50 UART Driver</title>
341
-
!Iinclude/linux/serial_core.h
342
-
!Edrivers/serial/serial_core.c
343
-
!Edrivers/serial/8250.c
344
-
</chapter>
345
-
346
-
<chapter id="fbdev">
347
-
<title>Frame Buffer Library</title>
348
-
349
-
<para>
350
-
The frame buffer drivers depend heavily on four data structures.
351
-
These structures are declared in include/linux/fb.h. They are
352
-
fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
353
-
The last three can be made available to and from userland.
354
-
</para>
355
-
356
-
<para>
357
-
fb_info defines the current state of a particular video card.
358
-
Inside fb_info, there exists a fb_ops structure which is a
359
-
collection of needed functions to make fbdev and fbcon work.
360
-
fb_info is only visible to the kernel.
361
-
</para>
362
-
363
-
<para>
364
-
fb_var_screeninfo is used to describe the features of a video card
365
-
that are user defined. With fb_var_screeninfo, things such as
366
-
depth and the resolution may be defined.
367
-
</para>
368
-
369
-
<para>
370
-
The next structure is fb_fix_screeninfo. This defines the
371
-
properties of a card that are created when a mode is set and can't
372
-
be changed otherwise. A good example of this is the start of the
373
-
frame buffer memory. This "locks" the address of the frame buffer
374
-
memory, so that it cannot be changed or moved.
375
-
</para>
376
-
377
-
<para>
378
-
The last structure is fb_monospecs. In the old API, there was
379
-
little importance for fb_monospecs. This allowed for forbidden things
380
-
such as setting a mode of 800x600 on a fix frequency monitor. With
381
-
the new API, fb_monospecs prevents such things, and if used
382
-
correctly, can prevent a monitor from being cooked. fb_monospecs
383
-
will not be useful until kernels 2.5.x.
384
-
</para>
385
-
386
-
<sect1><title>Frame Buffer Memory</title>
387
-
!Edrivers/video/fbmem.c
388
-
</sect1>
389
-
<!--
390
-
<sect1><title>Frame Buffer Console</title>
391
-
X!Edrivers/video/console/fbcon.c
392
-
</sect1>
393
-
-->
394
-
<sect1><title>Frame Buffer Colormap</title>
395
-
!Edrivers/video/fbcmap.c
396
-
</sect1>
397
-
<!-- FIXME:
398
-
drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
399
-
out until somebody adds docs. KAO
400
-
<sect1><title>Frame Buffer Generic Functions</title>
401
-
X!Idrivers/video/fbgen.c
402
-
</sect1>
403
-
KAO -->
404
-
<sect1><title>Frame Buffer Video Mode Database</title>
405
-
!Idrivers/video/modedb.c
406
-
!Edrivers/video/modedb.c
407
-
</sect1>
408
-
<sect1><title>Frame Buffer Macintosh Video Mode Database</title>
409
-
!Edrivers/video/macmodes.c
410
-
</sect1>
411
-
<sect1><title>Frame Buffer Fonts</title>
412
-
<para>
413
-
Refer to the file drivers/video/console/fonts.c for more information.
414
-
</para>
415
-
<!-- FIXME: Removed for now since no structured comments in source
416
-
X!Idrivers/video/console/fonts.c
417
-
-->
418
-
</sect1>
419
-
</chapter>
420
-
421
-
<chapter id="input_subsystem">
422
-
<title>Input Subsystem</title>
423
-
!Iinclude/linux/input.h
424
-
!Edrivers/input/input.c
425
-
!Edrivers/input/ff-core.c
426
-
!Edrivers/input/ff-memless.c
427
-
</chapter>
428
-
429
-
<chapter id="spi">
430
-
<title>Serial Peripheral Interface (SPI)</title>
431
-
<para>
432
-
SPI is the "Serial Peripheral Interface", widely used with
433
-
embedded systems because it is a simple and efficient
434
-
interface: basically a multiplexed shift register.
435
-
Its three signal wires hold a clock (SCK, often in the range
436
-
of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
437
-
a "Master In, Slave Out" (MISO) data line.
438
-
SPI is a full duplex protocol; for each bit shifted out the
439
-
MOSI line (one per clock) another is shifted in on the MISO line.
440
-
Those bits are assembled into words of various sizes on the
441
-
way to and from system memory.
442
-
An additional chipselect line is usually active-low (nCS);
443
-
four signals are normally used for each peripheral, plus
444
-
sometimes an interrupt.
445
-
</para>
446
-
<para>
447
-
The SPI bus facilities listed here provide a generalized
448
-
interface to declare SPI busses and devices, manage them
449
-
according to the standard Linux driver model, and perform
450
-
input/output operations.
451
-
At this time, only "master" side interfaces are supported,
452
-
where Linux talks to SPI peripherals and does not implement
453
-
such a peripheral itself.
454
-
(Interfaces to support implementing SPI slaves would
455
-
necessarily look different.)
456
-
</para>
457
-
<para>
458
-
The programming interface is structured around two kinds of driver,
459
-
and two kinds of device.
460
-
A "Controller Driver" abstracts the controller hardware, which may
461
-
be as simple as a set of GPIO pins or as complex as a pair of FIFOs
462
-
connected to dual DMA engines on the other side of the SPI shift
463
-
register (maximizing throughput). Such drivers bridge between
464
-
whatever bus they sit on (often the platform bus) and SPI, and
465
-
expose the SPI side of their device as a
466
-
<structname>struct spi_master</structname>.
467
-
SPI devices are children of that master, represented as a
468
-
<structname>struct spi_device</structname> and manufactured from
469
-
<structname>struct spi_board_info</structname> descriptors which
470
-
are usually provided by board-specific initialization code.
471
-
A <structname>struct spi_driver</structname> is called a
472
-
"Protocol Driver", and is bound to a spi_device using normal
473
-
driver model calls.
474
-
</para>
475
-
<para>
476
-
The I/O model is a set of queued messages. Protocol drivers
477
-
submit one or more <structname>struct spi_message</structname>
478
-
objects, which are processed and completed asynchronously.
479
-
(There are synchronous wrappers, however.) Messages are
480
-
built from one or more <structname>struct spi_transfer</structname>
481
-
objects, each of which wraps a full duplex SPI transfer.
482
-
A variety of protocol tweaking options are needed, because
483
-
different chips adopt very different policies for how they
484
-
use the bits transferred with SPI.
485
-
</para>
486
-
!Iinclude/linux/spi/spi.h
487
-
!Fdrivers/spi/spi.c spi_register_board_info
488
-
!Edrivers/spi/spi.c
489
-
</chapter>
490
-
491
-
<chapter id="i2c">
492
-
<title>I<superscript>2</superscript>C and SMBus Subsystem</title>
493
-
494
-
<para>
495
-
I<superscript>2</superscript>C (or without fancy typography, "I2C")
496
-
is an acronym for the "Inter-IC" bus, a simple bus protocol which is
497
-
widely used where low data rate communications suffice.
498
-
Since it's also a licensed trademark, some vendors use another
499
-
name (such as "Two-Wire Interface", TWI) for the same bus.
500
-
I2C only needs two signals (SCL for clock, SDA for data), conserving
501
-
board real estate and minimizing signal quality issues.
502
-
Most I2C devices use seven bit addresses, and bus speeds of up
503
-
to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
504
-
found wide use.
505
-
I2C is a multi-master bus; open drain signaling is used to
506
-
arbitrate between masters, as well as to handshake and to
507
-
synchronize clocks from slower clients.
508
-
</para>
509
-
510
-
<para>
511
-
The Linux I2C programming interfaces support only the master
512
-
side of bus interactions, not the slave side.
513
-
The programming interface is structured around two kinds of driver,
514
-
and two kinds of device.
515
-
An I2C "Adapter Driver" abstracts the controller hardware; it binds
516
-
to a physical device (perhaps a PCI device or platform_device) and
517
-
exposes a <structname>struct i2c_adapter</structname> representing
518
-
each I2C bus segment it manages.
519
-
On each I2C bus segment will be I2C devices represented by a
520
-
<structname>struct i2c_client</structname>. Those devices will
521
-
be bound to a <structname>struct i2c_driver</structname>,
522
-
which should follow the standard Linux driver model.
523
-
(At this writing, a legacy model is more widely used.)
524
-
There are functions to perform various I2C protocol operations; at
525
-
this writing all such functions are usable only from task context.
526
-
</para>
527
-
528
-
<para>
529
-
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
530
-
systems are also I2C conformant. The electrical constraints are
531
-
tighter for SMBus, and it standardizes particular protocol messages
532
-
and idioms. Controllers that support I2C can also support most
533
-
SMBus operations, but SMBus controllers don't support all the protocol
534
-
options that an I2C controller will.
535
-
There are functions to perform various SMBus protocol operations,
536
-
either using I2C primitives or by issuing SMBus commands to
537
-
i2c_adapter devices which don't support those I2C operations.
538
-
</para>
539
-
540
-
!Iinclude/linux/i2c.h
541
-
!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
542
-
!Edrivers/i2c/i2c-core.c
543
382
</chapter>
544
383
545
384
<chapter id="clk">