Commit | Line | Data |
---|---|---|
f7f84f38 RD |
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> | |
88b68033 | 48 | !Iarch/x86/include/asm/atomic.h |
f7f84f38 RD |
49 | </sect1> |
50 | ||
51 | <sect1><title>Delaying, scheduling, and timer routines</title> | |
52 | !Iinclude/linux/sched.h | |
b4d20859 RD |
53 | !Ekernel/sched/core.c |
54 | !Ikernel/sched/cpupri.c | |
55 | !Ikernel/sched/fair.c | |
ee2f154a | 56 | !Iinclude/linux/completion.h |
be11e6d8 | 57 | !Ekernel/time/timer.c |
ee2f154a RD |
58 | </sect1> |
59 | <sect1><title>Wait queues and Wake events</title> | |
60 | !Iinclude/linux/wait.h | |
96d5d9d9 | 61 | !Ekernel/sched/wait.c |
f7f84f38 RD |
62 | </sect1> |
63 | <sect1><title>High-resolution timers</title> | |
64 | !Iinclude/linux/ktime.h | |
65 | !Iinclude/linux/hrtimer.h | |
be11e6d8 | 66 | !Ekernel/time/hrtimer.c |
f7f84f38 RD |
67 | </sect1> |
68 | <sect1><title>Workqueues and Kevents</title> | |
81db32a3 | 69 | !Iinclude/linux/workqueue.h |
f7f84f38 RD |
70 | !Ekernel/workqueue.c |
71 | </sect1> | |
72 | <sect1><title>Internal Functions</title> | |
73 | !Ikernel/exit.c | |
74 | !Ikernel/signal.c | |
75 | !Iinclude/linux/kthread.h | |
76 | !Ekernel/kthread.c | |
77 | </sect1> | |
78 | ||
79 | <sect1><title>Kernel objects manipulation</title> | |
80 | <!-- | |
81 | X!Iinclude/linux/kobject.h | |
82 | --> | |
83 | !Elib/kobject.c | |
84 | </sect1> | |
85 | ||
86 | <sect1><title>Kernel utility functions</title> | |
87 | !Iinclude/linux/kernel.h | |
b9ee979e | 88 | !Ekernel/printk/printk.c |
f7f84f38 RD |
89 | !Ekernel/panic.c |
90 | !Ekernel/sys.c | |
4102adab PM |
91 | !Ekernel/rcu/srcu.c |
92 | !Ekernel/rcu/tree.c | |
93 | !Ekernel/rcu/tree_plugin.h | |
94 | !Ekernel/rcu/update.c | |
f7f84f38 RD |
95 | </sect1> |
96 | ||
97 | <sect1><title>Device Resource Management</title> | |
98 | !Edrivers/base/devres.c | |
99 | </sect1> | |
100 | ||
101 | </chapter> | |
102 | ||
103 | <chapter id="devdrivers"> | |
104 | <title>Device drivers infrastructure</title> | |
880ffb5c WG |
105 | <sect1><title>The Basic Device Driver-Model Structures </title> |
106 | !Iinclude/linux/device.h | |
107 | </sect1> | |
f7f84f38 | 108 | <sect1><title>Device Drivers Base</title> |
13405059 | 109 | !Idrivers/base/init.c |
f7f84f38 RD |
110 | !Edrivers/base/driver.c |
111 | !Edrivers/base/core.c | |
13405059 | 112 | !Edrivers/base/syscore.c |
f7f84f38 | 113 | !Edrivers/base/class.c |
13405059 | 114 | !Idrivers/base/node.c |
f7f84f38 RD |
115 | !Edrivers/base/firmware_class.c |
116 | !Edrivers/base/transport_class.c | |
117 | <!-- Cannot be included, because | |
118 | attribute_container_add_class_device_adapter | |
119 | and attribute_container_classdev_to_container | |
120 | exceed allowed 44 characters maximum | |
121 | X!Edrivers/base/attribute_container.c | |
122 | --> | |
13405059 | 123 | !Edrivers/base/dd.c |
f7f84f38 RD |
124 | <!-- |
125 | X!Edrivers/base/interface.c | |
126 | --> | |
44f28bde | 127 | !Iinclude/linux/platform_device.h |
f7f84f38 RD |
128 | !Edrivers/base/platform.c |
129 | !Edrivers/base/bus.c | |
13405059 | 130 | </sect1> |
eae1760f RC |
131 | <sect1> |
132 | <title>Buffer Sharing and Synchronization</title> | |
133 | <para> | |
134 | The dma-buf subsystem provides the framework for sharing buffers | |
135 | for hardware (DMA) access across multiple device drivers and | |
136 | subsystems, and for synchronizing asynchronous hardware access. | |
137 | </para> | |
138 | <para> | |
139 | This is used, for example, by drm "prime" multi-GPU support, but | |
140 | is of course not limited to GPU use cases. | |
141 | </para> | |
142 | <para> | |
143 | The three main components of this are: (1) dma-buf, representing | |
144 | a sg_table and exposed to userspace as a file descriptor to allow | |
145 | passing between devices, (2) fence, which provides a mechanism | |
146 | to signal when one device as finished access, and (3) reservation, | |
147 | which manages the shared or exclusive fence(s) associated with | |
148 | the buffer. | |
149 | </para> | |
150 | <sect2><title>dma-buf</title> | |
35fac7e3 | 151 | !Edrivers/dma-buf/dma-buf.c |
eae1760f RC |
152 | !Iinclude/linux/dma-buf.h |
153 | </sect2> | |
154 | <sect2><title>reservation</title> | |
155 | !Pdrivers/dma-buf/reservation.c Reservation Object Overview | |
156 | !Edrivers/dma-buf/reservation.c | |
157 | !Iinclude/linux/reservation.h | |
158 | </sect2> | |
159 | <sect2><title>fence</title> | |
e941759c ML |
160 | !Edrivers/dma-buf/fence.c |
161 | !Iinclude/linux/fence.h | |
eae1760f | 162 | !Edrivers/dma-buf/seqno-fence.c |
606b23ad | 163 | !Iinclude/linux/seqno-fence.h |
5b996e93 GP |
164 | !Edrivers/dma-buf/sync_file.c |
165 | !Iinclude/linux/sync_file.h | |
eae1760f RC |
166 | </sect2> |
167 | </sect1> | |
168 | <sect1><title>Device Drivers DMA Management</title> | |
13405059 RD |
169 | !Edrivers/base/dma-coherent.c |
170 | !Edrivers/base/dma-mapping.c | |
f7f84f38 RD |
171 | </sect1> |
172 | <sect1><title>Device Drivers Power Management</title> | |
173 | !Edrivers/base/power/main.c | |
174 | </sect1> | |
175 | <sect1><title>Device Drivers ACPI Support</title> | |
176 | <!-- Internal functions only | |
177 | X!Edrivers/acpi/sleep/main.c | |
178 | X!Edrivers/acpi/sleep/wakeup.c | |
179 | X!Edrivers/acpi/motherboard.c | |
180 | X!Edrivers/acpi/bus.c | |
181 | --> | |
182 | !Edrivers/acpi/scan.c | |
183 | !Idrivers/acpi/scan.c | |
184 | <!-- No correct structured comments | |
185 | X!Edrivers/acpi/pci_bind.c | |
186 | --> | |
187 | </sect1> | |
188 | <sect1><title>Device drivers PnP support</title> | |
189 | !Idrivers/pnp/core.c | |
190 | <!-- No correct structured comments | |
191 | X!Edrivers/pnp/system.c | |
192 | --> | |
193 | !Edrivers/pnp/card.c | |
194 | !Idrivers/pnp/driver.c | |
195 | !Edrivers/pnp/manager.c | |
196 | !Edrivers/pnp/support.c | |
197 | </sect1> | |
198 | <sect1><title>Userspace IO devices</title> | |
199 | !Edrivers/uio/uio.c | |
200 | !Iinclude/linux/uio_driver.h | |
201 | </sect1> | |
202 | </chapter> | |
203 | ||
204 | <chapter id="parportdev"> | |
205 | <title>Parallel Port Devices</title> | |
206 | !Iinclude/linux/parport.h | |
207 | !Edrivers/parport/ieee1284.c | |
208 | !Edrivers/parport/share.c | |
209 | !Idrivers/parport/daisy.c | |
210 | </chapter> | |
211 | ||
212 | <chapter id="message_devices"> | |
213 | <title>Message-based devices</title> | |
214 | <sect1><title>Fusion message devices</title> | |
215 | !Edrivers/message/fusion/mptbase.c | |
216 | !Idrivers/message/fusion/mptbase.c | |
217 | !Edrivers/message/fusion/mptscsih.c | |
218 | !Idrivers/message/fusion/mptscsih.c | |
219 | !Idrivers/message/fusion/mptctl.c | |
220 | !Idrivers/message/fusion/mptspi.c | |
221 | !Idrivers/message/fusion/mptfc.c | |
222 | !Idrivers/message/fusion/mptlan.c | |
223 | </sect1> | |
f7f84f38 RD |
224 | </chapter> |
225 | ||
226 | <chapter id="snddev"> | |
227 | <title>Sound Devices</title> | |
228 | !Iinclude/sound/core.h | |
229 | !Esound/sound_core.c | |
230 | !Iinclude/sound/pcm.h | |
231 | !Esound/core/pcm.c | |
232 | !Esound/core/device.c | |
233 | !Esound/core/info.c | |
234 | !Esound/core/rawmidi.c | |
235 | !Esound/core/sound.c | |
236 | !Esound/core/memory.c | |
237 | !Esound/core/pcm_memory.c | |
238 | !Esound/core/init.c | |
239 | !Esound/core/isadma.c | |
240 | !Esound/core/control.c | |
241 | !Esound/core/pcm_lib.c | |
242 | !Esound/core/hwdep.c | |
243 | !Esound/core/pcm_native.c | |
244 | !Esound/core/memalloc.c | |
245 | <!-- FIXME: Removed for now since no structured comments in source | |
246 | X!Isound/sound_firmware.c | |
247 | --> | |
248 | </chapter> | |
249 | ||
dc2c8bd3 MCC |
250 | <chapter id="mediadev"> |
251 | <title>Media Devices</title> | |
04ffb9c1 MCC |
252 | |
253 | <sect1><title>Video2Linux devices</title> | |
07c68a74 | 254 | !Iinclude/media/tuner.h |
5057f326 | 255 | !Iinclude/media/tuner-types.h |
326ab27b | 256 | !Iinclude/media/tveeprom.h |
dc2c8bd3 | 257 | !Iinclude/media/v4l2-async.h |
04ffb9c1 MCC |
258 | !Iinclude/media/v4l2-ctrls.h |
259 | !Iinclude/media/v4l2-dv-timings.h | |
260 | !Iinclude/media/v4l2-event.h | |
dc2c8bd3 | 261 | !Iinclude/media/v4l2-flash-led-class.h |
6aad127d | 262 | !Iinclude/media/v4l2-mc.h |
04ffb9c1 | 263 | !Iinclude/media/v4l2-mediabus.h |
dc2c8bd3 MCC |
264 | !Iinclude/media/v4l2-mem2mem.h |
265 | !Iinclude/media/v4l2-of.h | |
ac49de8c | 266 | !Iinclude/media/v4l2-rect.h |
dc2c8bd3 | 267 | !Iinclude/media/v4l2-subdev.h |
04ffb9c1 | 268 | !Iinclude/media/videobuf2-core.h |
1ccd66cc | 269 | !Iinclude/media/videobuf2-v4l2.h |
04ffb9c1 MCC |
270 | !Iinclude/media/videobuf2-memops.h |
271 | </sect1> | |
272 | <sect1><title>Digital TV (DVB) devices</title> | |
6747b394 | 273 | <sect1><title>Digital TV Common functions</title> |
e08bb6f7 | 274 | !Idrivers/media/dvb-core/dvb_math.h |
2a86e373 | 275 | !Idrivers/media/dvb-core/dvb_ringbuffer.h |
d071c833 | 276 | !Idrivers/media/dvb-core/dvbdev.h |
6747b394 MCC |
277 | </sect1> |
278 | <sect1><title>Digital TV Frontend kABI</title> | |
02f028cf | 279 | !Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend |
6747b394 MCC |
280 | !Idrivers/media/dvb-core/dvb_frontend.h |
281 | </sect1> | |
282 | <sect1><title>Digital TV Demux kABI</title> | |
283 | !Pdrivers/media/dvb-core/demux.h Digital TV Demux | |
284 | <sect1><title>Demux Callback API</title> | |
285 | !Pdrivers/media/dvb-core/demux.h Demux Callback | |
286 | </sect1> | |
de08e701 | 287 | !Idrivers/media/dvb-core/demux.h |
6747b394 MCC |
288 | </sect1> |
289 | <sect1><title>Digital TV Conditional Access kABI</title> | |
290 | !Idrivers/media/dvb-core/dvb_ca_en50221.h | |
291 | </sect1> | |
292 | </sect1> | |
de08e701 | 293 | <sect1><title>Remote Controller devices</title> |
04ffb9c1 | 294 | !Iinclude/media/rc-core.h |
be14c5cd | 295 | !Iinclude/media/lirc_dev.h |
de08e701 MCC |
296 | </sect1> |
297 | <sect1><title>Media Controller devices</title> | |
cc2dd94a | 298 | !Pinclude/media/media-device.h Media Controller |
04ffb9c1 MCC |
299 | !Iinclude/media/media-device.h |
300 | !Iinclude/media/media-devnode.h | |
301 | !Iinclude/media/media-entity.h | |
de08e701 | 302 | </sect1> |
dc2c8bd3 MCC |
303 | |
304 | </chapter> | |
305 | ||
f7f84f38 RD |
306 | <chapter id="uart16x50"> |
307 | <title>16x50 UART Driver</title> | |
fcf28564 | 308 | !Edrivers/tty/serial/serial_core.c |
5448bd8c | 309 | !Edrivers/tty/serial/8250/8250_core.c |
f7f84f38 RD |
310 | </chapter> |
311 | ||
312 | <chapter id="fbdev"> | |
313 | <title>Frame Buffer Library</title> | |
314 | ||
315 | <para> | |
316 | The frame buffer drivers depend heavily on four data structures. | |
317 | These structures are declared in include/linux/fb.h. They are | |
318 | fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. | |
319 | The last three can be made available to and from userland. | |
320 | </para> | |
321 | ||
322 | <para> | |
323 | fb_info defines the current state of a particular video card. | |
324 | Inside fb_info, there exists a fb_ops structure which is a | |
325 | collection of needed functions to make fbdev and fbcon work. | |
326 | fb_info is only visible to the kernel. | |
327 | </para> | |
328 | ||
329 | <para> | |
330 | fb_var_screeninfo is used to describe the features of a video card | |
331 | that are user defined. With fb_var_screeninfo, things such as | |
332 | depth and the resolution may be defined. | |
333 | </para> | |
334 | ||
335 | <para> | |
336 | The next structure is fb_fix_screeninfo. This defines the | |
337 | properties of a card that are created when a mode is set and can't | |
338 | be changed otherwise. A good example of this is the start of the | |
339 | frame buffer memory. This "locks" the address of the frame buffer | |
340 | memory, so that it cannot be changed or moved. | |
341 | </para> | |
342 | ||
343 | <para> | |
344 | The last structure is fb_monospecs. In the old API, there was | |
345 | little importance for fb_monospecs. This allowed for forbidden things | |
346 | such as setting a mode of 800x600 on a fix frequency monitor. With | |
347 | the new API, fb_monospecs prevents such things, and if used | |
348 | correctly, can prevent a monitor from being cooked. fb_monospecs | |
349 | will not be useful until kernels 2.5.x. | |
350 | </para> | |
351 | ||
352 | <sect1><title>Frame Buffer Memory</title> | |
19757fc8 | 353 | !Edrivers/video/fbdev/core/fbmem.c |
f7f84f38 RD |
354 | </sect1> |
355 | <!-- | |
356 | <sect1><title>Frame Buffer Console</title> | |
357 | X!Edrivers/video/console/fbcon.c | |
358 | </sect1> | |
359 | --> | |
360 | <sect1><title>Frame Buffer Colormap</title> | |
19757fc8 | 361 | !Edrivers/video/fbdev/core/fbcmap.c |
f7f84f38 RD |
362 | </sect1> |
363 | <!-- FIXME: | |
364 | drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment | |
365 | out until somebody adds docs. KAO | |
366 | <sect1><title>Frame Buffer Generic Functions</title> | |
367 | X!Idrivers/video/fbgen.c | |
368 | </sect1> | |
369 | KAO --> | |
370 | <sect1><title>Frame Buffer Video Mode Database</title> | |
19757fc8 TV |
371 | !Idrivers/video/fbdev/core/modedb.c |
372 | !Edrivers/video/fbdev/core/modedb.c | |
f7f84f38 RD |
373 | </sect1> |
374 | <sect1><title>Frame Buffer Macintosh Video Mode Database</title> | |
f7018c21 | 375 | !Edrivers/video/fbdev/macmodes.c |
f7f84f38 RD |
376 | </sect1> |
377 | <sect1><title>Frame Buffer Fonts</title> | |
378 | <para> | |
ee89bd6b | 379 | Refer to the file lib/fonts/fonts.c for more information. |
f7f84f38 RD |
380 | </para> |
381 | <!-- FIXME: Removed for now since no structured comments in source | |
ee89bd6b | 382 | X!Ilib/fonts/fonts.c |
f7f84f38 RD |
383 | --> |
384 | </sect1> | |
385 | </chapter> | |
386 | ||
387 | <chapter id="input_subsystem"> | |
388 | <title>Input Subsystem</title> | |
d69249f4 | 389 | <sect1><title>Input core</title> |
f7f84f38 RD |
390 | !Iinclude/linux/input.h |
391 | !Edrivers/input/input.c | |
392 | !Edrivers/input/ff-core.c | |
393 | !Edrivers/input/ff-memless.c | |
69479f8d DT |
394 | </sect1> |
395 | <sect1><title>Multitouch Library</title> | |
396 | !Iinclude/linux/input/mt.h | |
397 | !Edrivers/input/input-mt.c | |
d69249f4 DT |
398 | </sect1> |
399 | <sect1><title>Polled input devices</title> | |
400 | !Iinclude/linux/input-polldev.h | |
401 | !Edrivers/input/input-polldev.c | |
402 | </sect1> | |
abaa5c23 | 403 | <sect1><title>Matrix keyboards/keypads</title> |
d69249f4 DT |
404 | !Iinclude/linux/input/matrix_keypad.h |
405 | </sect1> | |
36203c4f DT |
406 | <sect1><title>Sparse keymap support</title> |
407 | !Iinclude/linux/input/sparse-keymap.h | |
408 | !Edrivers/input/sparse-keymap.c | |
409 | </sect1> | |
f7f84f38 RD |
410 | </chapter> |
411 | ||
412 | <chapter id="spi"> | |
413 | <title>Serial Peripheral Interface (SPI)</title> | |
414 | <para> | |
415 | SPI is the "Serial Peripheral Interface", widely used with | |
416 | embedded systems because it is a simple and efficient | |
417 | interface: basically a multiplexed shift register. | |
418 | Its three signal wires hold a clock (SCK, often in the range | |
419 | of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and | |
420 | a "Master In, Slave Out" (MISO) data line. | |
421 | SPI is a full duplex protocol; for each bit shifted out the | |
422 | MOSI line (one per clock) another is shifted in on the MISO line. | |
423 | Those bits are assembled into words of various sizes on the | |
424 | way to and from system memory. | |
425 | An additional chipselect line is usually active-low (nCS); | |
426 | four signals are normally used for each peripheral, plus | |
427 | sometimes an interrupt. | |
428 | </para> | |
429 | <para> | |
430 | The SPI bus facilities listed here provide a generalized | |
431 | interface to declare SPI busses and devices, manage them | |
432 | according to the standard Linux driver model, and perform | |
433 | input/output operations. | |
434 | At this time, only "master" side interfaces are supported, | |
435 | where Linux talks to SPI peripherals and does not implement | |
436 | such a peripheral itself. | |
437 | (Interfaces to support implementing SPI slaves would | |
438 | necessarily look different.) | |
439 | </para> | |
440 | <para> | |
441 | The programming interface is structured around two kinds of driver, | |
442 | and two kinds of device. | |
443 | A "Controller Driver" abstracts the controller hardware, which may | |
444 | be as simple as a set of GPIO pins or as complex as a pair of FIFOs | |
445 | connected to dual DMA engines on the other side of the SPI shift | |
446 | register (maximizing throughput). Such drivers bridge between | |
447 | whatever bus they sit on (often the platform bus) and SPI, and | |
448 | expose the SPI side of their device as a | |
449 | <structname>struct spi_master</structname>. | |
450 | SPI devices are children of that master, represented as a | |
451 | <structname>struct spi_device</structname> and manufactured from | |
452 | <structname>struct spi_board_info</structname> descriptors which | |
453 | are usually provided by board-specific initialization code. | |
454 | A <structname>struct spi_driver</structname> is called a | |
455 | "Protocol Driver", and is bound to a spi_device using normal | |
456 | driver model calls. | |
457 | </para> | |
458 | <para> | |
459 | The I/O model is a set of queued messages. Protocol drivers | |
460 | submit one or more <structname>struct spi_message</structname> | |
461 | objects, which are processed and completed asynchronously. | |
462 | (There are synchronous wrappers, however.) Messages are | |
463 | built from one or more <structname>struct spi_transfer</structname> | |
464 | objects, each of which wraps a full duplex SPI transfer. | |
465 | A variety of protocol tweaking options are needed, because | |
466 | different chips adopt very different policies for how they | |
467 | use the bits transferred with SPI. | |
468 | </para> | |
469 | !Iinclude/linux/spi/spi.h | |
470 | !Fdrivers/spi/spi.c spi_register_board_info | |
471 | !Edrivers/spi/spi.c | |
472 | </chapter> | |
473 | ||
474 | <chapter id="i2c"> | |
475 | <title>I<superscript>2</superscript>C and SMBus Subsystem</title> | |
476 | ||
477 | <para> | |
478 | I<superscript>2</superscript>C (or without fancy typography, "I2C") | |
479 | is an acronym for the "Inter-IC" bus, a simple bus protocol which is | |
480 | widely used where low data rate communications suffice. | |
481 | Since it's also a licensed trademark, some vendors use another | |
482 | name (such as "Two-Wire Interface", TWI) for the same bus. | |
483 | I2C only needs two signals (SCL for clock, SDA for data), conserving | |
484 | board real estate and minimizing signal quality issues. | |
485 | Most I2C devices use seven bit addresses, and bus speeds of up | |
486 | to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet | |
487 | found wide use. | |
488 | I2C is a multi-master bus; open drain signaling is used to | |
489 | arbitrate between masters, as well as to handshake and to | |
490 | synchronize clocks from slower clients. | |
491 | </para> | |
492 | ||
493 | <para> | |
494 | The Linux I2C programming interfaces support only the master | |
495 | side of bus interactions, not the slave side. | |
496 | The programming interface is structured around two kinds of driver, | |
497 | and two kinds of device. | |
498 | An I2C "Adapter Driver" abstracts the controller hardware; it binds | |
499 | to a physical device (perhaps a PCI device or platform_device) and | |
500 | exposes a <structname>struct i2c_adapter</structname> representing | |
501 | each I2C bus segment it manages. | |
502 | On each I2C bus segment will be I2C devices represented by a | |
503 | <structname>struct i2c_client</structname>. Those devices will | |
504 | be bound to a <structname>struct i2c_driver</structname>, | |
505 | which should follow the standard Linux driver model. | |
506 | (At this writing, a legacy model is more widely used.) | |
507 | There are functions to perform various I2C protocol operations; at | |
508 | this writing all such functions are usable only from task context. | |
509 | </para> | |
510 | ||
511 | <para> | |
512 | The System Management Bus (SMBus) is a sibling protocol. Most SMBus | |
513 | systems are also I2C conformant. The electrical constraints are | |
514 | tighter for SMBus, and it standardizes particular protocol messages | |
515 | and idioms. Controllers that support I2C can also support most | |
516 | SMBus operations, but SMBus controllers don't support all the protocol | |
517 | options that an I2C controller will. | |
518 | There are functions to perform various SMBus protocol operations, | |
519 | either using I2C primitives or by issuing SMBus commands to | |
520 | i2c_adapter devices which don't support those I2C operations. | |
521 | </para> | |
522 | ||
523 | !Iinclude/linux/i2c.h | |
524 | !Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info | |
525 | !Edrivers/i2c/i2c-core.c | |
526 | </chapter> | |
527 | ||
a4ac73a7 CC |
528 | <chapter id="hsi"> |
529 | <title>High Speed Synchronous Serial Interface (HSI)</title> | |
530 | ||
531 | <para> | |
532 | High Speed Synchronous Serial Interface (HSI) is a | |
533 | serial interface mainly used for connecting application | |
534 | engines (APE) with cellular modem engines (CMT) in cellular | |
535 | handsets. | |
536 | ||
537 | HSI provides multiplexing for up to 16 logical channels, | |
538 | low-latency and full duplex communication. | |
539 | </para> | |
540 | ||
541 | !Iinclude/linux/hsi/hsi.h | |
542 | !Edrivers/hsi/hsi.c | |
543 | </chapter> | |
544 | ||
6e146f5c TR |
545 | <chapter id="pwm"> |
546 | <title>Pulse-Width Modulation (PWM)</title> | |
547 | <para> | |
548 | Pulse-width modulation is a modulation technique primarily used to | |
549 | control power supplied to electrical devices. | |
550 | </para> | |
551 | <para> | |
552 | The PWM framework provides an abstraction for providers and consumers | |
553 | of PWM signals. A controller that provides one or more PWM signals is | |
554 | registered as <structname>struct pwm_chip</structname>. Providers are | |
555 | expected to embed this structure in a driver-specific structure. This | |
556 | structure contains fields that describe a particular chip. | |
557 | </para> | |
558 | <para> | |
559 | A chip exposes one or more PWM signal sources, each of which exposed | |
560 | as a <structname>struct pwm_device</structname>. Operations can be | |
561 | performed on PWM devices to control the period, duty cycle, polarity | |
562 | and active state of the signal. | |
563 | </para> | |
564 | <para> | |
565 | Note that PWM devices are exclusive resources: they can always only be | |
566 | used by one consumer at a time. | |
567 | </para> | |
568 | !Iinclude/linux/pwm.h | |
569 | !Edrivers/pwm/core.c | |
570 | </chapter> | |
571 | ||
f7f84f38 | 572 | </book> |