About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / device-drivers.tmpl




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.

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.h
49	     </sect1>
50	
51	     <sect1><title>Delaying, scheduling, and timer routines</title>
52	!Iinclude/linux/sched.h
53	!Ekernel/sched/core.c
54	!Ikernel/sched/cpupri.c
55	!Ikernel/sched/fair.c
56	!Iinclude/linux/completion.h
57	!Ekernel/time/timer.c
58	     </sect1>
59	     <sect1><title>Wait queues and Wake events</title>
60	!Iinclude/linux/wait.h
61	!Ekernel/sched/wait.c
62	     </sect1>
63	     <sect1><title>High-resolution timers</title>
64	!Iinclude/linux/ktime.h
65	!Iinclude/linux/hrtimer.h
66	!Ekernel/time/hrtimer.c
67	     </sect1>
68	     <sect1><title>Workqueues and Kevents</title>
69	!Iinclude/linux/workqueue.h
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
88	!Ekernel/printk/printk.c
89	!Ekernel/panic.c
90	!Ekernel/sys.c
91	!Ekernel/rcu/srcu.c
92	!Ekernel/rcu/tree.c
93	!Ekernel/rcu/tree_plugin.h
94	!Ekernel/rcu/update.c
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>
105	     <sect1><title>The Basic Device Driver-Model Structures </title>
106	!Iinclude/linux/device.h
107	     </sect1>
108	     <sect1><title>Device Drivers Base</title>
109	!Idrivers/base/init.c
110	!Edrivers/base/driver.c
111	!Edrivers/base/core.c
112	!Edrivers/base/syscore.c
113	!Edrivers/base/class.c
114	!Idrivers/base/node.c
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	-->
123	!Edrivers/base/dd.c
124	<!--
125	X!Edrivers/base/interface.c
126	-->
127	!Iinclude/linux/platform_device.h
128	!Edrivers/base/platform.c
129	!Edrivers/base/bus.c
130	     </sect1>
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>
151	!Edrivers/dma-buf/dma-buf.c
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>
160	!Edrivers/dma-buf/fence.c
161	!Iinclude/linux/fence.h
162	!Edrivers/dma-buf/seqno-fence.c
163	!Iinclude/linux/seqno-fence.h
164	!Edrivers/dma-buf/sync_file.c
165	!Iinclude/linux/sync_file.h
166	       </sect2>
167	     </sect1>
168	     <sect1><title>Device Drivers DMA Management</title>
169	!Edrivers/base/dma-coherent.c
170	!Edrivers/base/dma-mapping.c
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>
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	
250	  <chapter id="mediadev">
251	     <title>Media Devices</title>
252	
253	     <sect1><title>Video2Linux devices</title>
254	!Iinclude/media/tuner.h
255	!Iinclude/media/tuner-types.h
256	!Iinclude/media/tveeprom.h
257	!Iinclude/media/v4l2-async.h
258	!Iinclude/media/v4l2-ctrls.h
259	!Iinclude/media/v4l2-dv-timings.h
260	!Iinclude/media/v4l2-event.h
261	!Iinclude/media/v4l2-flash-led-class.h
262	!Iinclude/media/v4l2-mc.h
263	!Iinclude/media/v4l2-mediabus.h
264	!Iinclude/media/v4l2-mem2mem.h
265	!Iinclude/media/v4l2-of.h
266	!Iinclude/media/v4l2-rect.h
267	!Iinclude/media/v4l2-subdev.h
268	!Iinclude/media/videobuf2-core.h
269	!Iinclude/media/videobuf2-v4l2.h
270	!Iinclude/media/videobuf2-memops.h
271	     </sect1>
272	     <sect1><title>Digital TV (DVB) devices</title>
273		<sect1><title>Digital TV Common functions</title>
274	!Idrivers/media/dvb-core/dvb_math.h
275	!Idrivers/media/dvb-core/dvb_ringbuffer.h
276	!Idrivers/media/dvb-core/dvbdev.h
277		</sect1>
278		<sect1><title>Digital TV Frontend kABI</title>
279	!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
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>
287	!Idrivers/media/dvb-core/demux.h
288		</sect1>
289		<sect1><title>Digital TV Conditional Access kABI</title>
290	!Idrivers/media/dvb-core/dvb_ca_en50221.h
291		</sect1>
292	     </sect1>
293	    <sect1><title>Remote Controller devices</title>
294	!Iinclude/media/rc-core.h
295	!Iinclude/media/lirc_dev.h
296	    </sect1>
297	    <sect1><title>Media Controller devices</title>
298	!Pinclude/media/media-device.h Media Controller
299	!Iinclude/media/media-device.h
300	!Iinclude/media/media-devnode.h
301	!Iinclude/media/media-entity.h
302	    </sect1>
303	
304	  </chapter>
305	
306	  <chapter id="uart16x50">
307	     <title>16x50 UART Driver</title>
308	!Edrivers/tty/serial/serial_core.c
309	!Edrivers/tty/serial/8250/8250_core.c
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>
353	!Edrivers/video/fbdev/core/fbmem.c
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>
361	!Edrivers/video/fbdev/core/fbcmap.c
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>
371	!Idrivers/video/fbdev/core/modedb.c
372	!Edrivers/video/fbdev/core/modedb.c
373	     </sect1>
374	     <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
375	!Edrivers/video/fbdev/macmodes.c
376	     </sect1>
377	     <sect1><title>Frame Buffer Fonts</title>
378	        <para>
379	           Refer to the file lib/fonts/fonts.c for more information.
380	        </para>
381	<!-- FIXME: Removed for now since no structured comments in source
382	X!Ilib/fonts/fonts.c
383	-->
384	     </sect1>
385	  </chapter>
386	
387	  <chapter id="input_subsystem">
388	     <title>Input Subsystem</title>
389	     <sect1><title>Input core</title>
390	!Iinclude/linux/input.h
391	!Edrivers/input/input.c
392	!Edrivers/input/ff-core.c
393	!Edrivers/input/ff-memless.c
394	     </sect1>
395	     <sect1><title>Multitouch Library</title>
396	!Iinclude/linux/input/mt.h
397	!Edrivers/input/input-mt.c
398	     </sect1>
399	     <sect1><title>Polled input devices</title>
400	!Iinclude/linux/input-polldev.h
401	!Edrivers/input/input-polldev.c
402	     </sect1>
403	     <sect1><title>Matrix keyboards/keypads</title>
404	!Iinclude/linux/input/matrix_keypad.h
405	     </sect1>
406	     <sect1><title>Sparse keymap support</title>
407	!Iinclude/linux/input/sparse-keymap.h
408	!Edrivers/input/sparse-keymap.c
409	     </sect1>
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	
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	
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	
572	</book>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.