Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 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> |
Randy Dunlap | 88b6803 | 2010-03-01 22:06:25 -0800 | [diff] [blame] | 48 | !Iarch/x86/include/asm/atomic.h |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 49 | </sect1> |
| 50 | |
| 51 | <sect1><title>Delaying, scheduling, and timer routines</title> |
| 52 | !Iinclude/linux/sched.h |
Randy Dunlap | b4d2085 | 2012-01-21 11:03:24 -0800 | [diff] [blame] | 53 | !Ekernel/sched/core.c |
| 54 | !Ikernel/sched/cpupri.c |
| 55 | !Ikernel/sched/fair.c |
Randy Dunlap | ee2f154 | 2010-10-26 14:17:25 -0700 | [diff] [blame] | 56 | !Iinclude/linux/completion.h |
Masanari Iida | be11e6d | 2014-07-11 03:43:50 +0900 | [diff] [blame] | 57 | !Ekernel/time/timer.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 58 | </sect1> |
Randy Dunlap | ee2f154 | 2010-10-26 14:17:25 -0700 | [diff] [blame] | 59 | <sect1><title>Wait queues and Wake events</title> |
| 60 | !Iinclude/linux/wait.h |
Nicolas Dichtel | 96d5d9d | 2013-11-20 09:50:28 +0100 | [diff] [blame] | 61 | !Ekernel/sched/wait.c |
Randy Dunlap | ee2f154 | 2010-10-26 14:17:25 -0700 | [diff] [blame] | 62 | </sect1> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 63 | <sect1><title>High-resolution timers</title> |
| 64 | !Iinclude/linux/ktime.h |
| 65 | !Iinclude/linux/hrtimer.h |
Masanari Iida | be11e6d | 2014-07-11 03:43:50 +0900 | [diff] [blame] | 66 | !Ekernel/time/hrtimer.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 67 | </sect1> |
| 68 | <sect1><title>Workqueues and Kevents</title> |
Tim Bird | 81db32a | 2015-08-10 15:16:16 -0700 | [diff] [blame] | 69 | !Iinclude/linux/workqueue.h |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 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 |
Joe Perches | b9ee979 | 2013-07-31 13:53:42 -0700 | [diff] [blame] | 88 | !Ekernel/printk/printk.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 89 | !Ekernel/panic.c |
| 90 | !Ekernel/sys.c |
Paul E. McKenney | 4102ada | 2013-10-08 20:23:47 -0700 | [diff] [blame] | 91 | !Ekernel/rcu/srcu.c |
| 92 | !Ekernel/rcu/tree.c |
| 93 | !Ekernel/rcu/tree_plugin.h |
| 94 | !Ekernel/rcu/update.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 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> |
Wanlong Gao | 880ffb5 | 2011-05-05 07:55:36 +0800 | [diff] [blame] | 105 | <sect1><title>The Basic Device Driver-Model Structures </title> |
| 106 | !Iinclude/linux/device.h |
| 107 | </sect1> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 108 | <sect1><title>Device Drivers Base</title> |
Randy Dunlap | 1340505 | 2012-02-01 18:15:49 -0800 | [diff] [blame] | 109 | !Idrivers/base/init.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 110 | !Edrivers/base/driver.c |
| 111 | !Edrivers/base/core.c |
Randy Dunlap | 1340505 | 2012-02-01 18:15:49 -0800 | [diff] [blame] | 112 | !Edrivers/base/syscore.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 113 | !Edrivers/base/class.c |
Randy Dunlap | 1340505 | 2012-02-01 18:15:49 -0800 | [diff] [blame] | 114 | !Idrivers/base/node.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 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 | --> |
Randy Dunlap | 1340505 | 2012-02-01 18:15:49 -0800 | [diff] [blame] | 123 | !Edrivers/base/dd.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 124 | <!-- |
| 125 | X!Edrivers/base/interface.c |
| 126 | --> |
Uwe Kleine-König | 44f28bd | 2010-06-21 16:11:44 +0200 | [diff] [blame] | 127 | !Iinclude/linux/platform_device.h |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 128 | !Edrivers/base/platform.c |
| 129 | !Edrivers/base/bus.c |
| 130 | </sect1> |
Rob Clark | eae1760 | 2016-03-31 16:26:52 -0400 | [diff] [blame] | 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> |
Maarten Lankhorst | 35fac7e | 2014-07-01 12:57:08 +0200 | [diff] [blame] | 151 | !Edrivers/dma-buf/dma-buf.c |
Rob Clark | eae1760 | 2016-03-31 16:26:52 -0400 | [diff] [blame] | 152 | !Iinclude/linux/dma-buf.h |
| 153 | </sect2> |
| 154 | <sect2><title>reservation</title> |
| 155 | !Pdrivers/dma-buf/reservation.c Reservation Object Overview |
Maarten Lankhorst | 04a5faa | 2014-07-01 12:57:54 +0200 | [diff] [blame] | 156 | !Edrivers/dma-buf/reservation.c |
Maarten Lankhorst | 786d725 | 2013-06-27 13:48:16 +0200 | [diff] [blame] | 157 | !Iinclude/linux/reservation.h |
Rob Clark | eae1760 | 2016-03-31 16:26:52 -0400 | [diff] [blame] | 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 |
Dave Airlie | 2cca455 | 2016-06-09 11:19:28 +1000 | [diff] [blame] | 164 | !Edrivers/dma-buf/fence-array.c |
Gustavo Padovan | ddac4b5 | 2016-06-06 12:21:05 -0300 | [diff] [blame] | 165 | !Iinclude/linux/fence-array.h |
Randy Dunlap | 1340505 | 2012-02-01 18:15:49 -0800 | [diff] [blame] | 166 | !Edrivers/dma-buf/reservation.c |
| 167 | !Iinclude/linux/reservation.h |
Gustavo Padovan | 5b996e9 | 2016-04-28 10:46:59 -0300 | [diff] [blame] | 168 | !Edrivers/dma-buf/sync_file.c |
| 169 | !Iinclude/linux/sync_file.h |
Rob Clark | eae1760 | 2016-03-31 16:26:52 -0400 | [diff] [blame] | 170 | </sect2> |
| 171 | </sect1> |
| 172 | <sect1><title>Device Drivers DMA Management</title> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 173 | !Edrivers/base/dma-coherent.c |
| 174 | !Edrivers/base/dma-mapping.c |
| 175 | </sect1> |
| 176 | <sect1><title>Device Drivers Power Management</title> |
| 177 | !Edrivers/base/power/main.c |
| 178 | </sect1> |
| 179 | <sect1><title>Device Drivers ACPI Support</title> |
| 180 | <!-- Internal functions only |
| 181 | X!Edrivers/acpi/sleep/main.c |
| 182 | X!Edrivers/acpi/sleep/wakeup.c |
| 183 | X!Edrivers/acpi/motherboard.c |
| 184 | X!Edrivers/acpi/bus.c |
| 185 | --> |
| 186 | !Edrivers/acpi/scan.c |
| 187 | !Idrivers/acpi/scan.c |
| 188 | <!-- No correct structured comments |
| 189 | X!Edrivers/acpi/pci_bind.c |
| 190 | --> |
| 191 | </sect1> |
| 192 | <sect1><title>Device drivers PnP support</title> |
| 193 | !Idrivers/pnp/core.c |
| 194 | <!-- No correct structured comments |
| 195 | X!Edrivers/pnp/system.c |
| 196 | --> |
| 197 | !Edrivers/pnp/card.c |
| 198 | !Idrivers/pnp/driver.c |
| 199 | !Edrivers/pnp/manager.c |
| 200 | !Edrivers/pnp/support.c |
| 201 | </sect1> |
| 202 | <sect1><title>Userspace IO devices</title> |
| 203 | !Edrivers/uio/uio.c |
| 204 | !Iinclude/linux/uio_driver.h |
| 205 | </sect1> |
| 206 | </chapter> |
| 207 | |
| 208 | <chapter id="parportdev"> |
| 209 | <title>Parallel Port Devices</title> |
| 210 | !Iinclude/linux/parport.h |
| 211 | !Edrivers/parport/ieee1284.c |
| 212 | !Edrivers/parport/share.c |
| 213 | !Idrivers/parport/daisy.c |
| 214 | </chapter> |
| 215 | |
| 216 | <chapter id="message_devices"> |
| 217 | <title>Message-based devices</title> |
| 218 | <sect1><title>Fusion message devices</title> |
| 219 | !Edrivers/message/fusion/mptbase.c |
| 220 | !Idrivers/message/fusion/mptbase.c |
| 221 | !Edrivers/message/fusion/mptscsih.c |
| 222 | !Idrivers/message/fusion/mptscsih.c |
| 223 | !Idrivers/message/fusion/mptctl.c |
| 224 | !Idrivers/message/fusion/mptspi.c |
| 225 | !Idrivers/message/fusion/mptfc.c |
| 226 | !Idrivers/message/fusion/mptlan.c |
| 227 | </sect1> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 228 | </chapter> |
| 229 | |
| 230 | <chapter id="snddev"> |
| 231 | <title>Sound Devices</title> |
| 232 | !Iinclude/sound/core.h |
| 233 | !Esound/sound_core.c |
| 234 | !Iinclude/sound/pcm.h |
| 235 | !Esound/core/pcm.c |
| 236 | !Esound/core/device.c |
| 237 | !Esound/core/info.c |
| 238 | !Esound/core/rawmidi.c |
| 239 | !Esound/core/sound.c |
| 240 | !Esound/core/memory.c |
| 241 | !Esound/core/pcm_memory.c |
| 242 | !Esound/core/init.c |
| 243 | !Esound/core/isadma.c |
| 244 | !Esound/core/control.c |
| 245 | !Esound/core/pcm_lib.c |
| 246 | !Esound/core/hwdep.c |
| 247 | !Esound/core/pcm_native.c |
| 248 | !Esound/core/memalloc.c |
| 249 | <!-- FIXME: Removed for now since no structured comments in source |
| 250 | X!Isound/sound_firmware.c |
| 251 | --> |
| 252 | </chapter> |
| 253 | |
Mauro Carvalho Chehab | dc2c8bd | 2015-08-21 14:17:13 -0300 | [diff] [blame] | 254 | |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 255 | <chapter id="uart16x50"> |
| 256 | <title>16x50 UART Driver</title> |
Randy Dunlap | fcf2856 | 2011-01-22 19:50:03 -0800 | [diff] [blame] | 257 | !Edrivers/tty/serial/serial_core.c |
Guennadi Liakhovetski | 5448bd8 | 2013-04-02 18:39:53 +0200 | [diff] [blame] | 258 | !Edrivers/tty/serial/8250/8250_core.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 259 | </chapter> |
| 260 | |
| 261 | <chapter id="fbdev"> |
| 262 | <title>Frame Buffer Library</title> |
| 263 | |
| 264 | <para> |
| 265 | The frame buffer drivers depend heavily on four data structures. |
| 266 | These structures are declared in include/linux/fb.h. They are |
| 267 | fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. |
| 268 | The last three can be made available to and from userland. |
| 269 | </para> |
| 270 | |
| 271 | <para> |
| 272 | fb_info defines the current state of a particular video card. |
| 273 | Inside fb_info, there exists a fb_ops structure which is a |
| 274 | collection of needed functions to make fbdev and fbcon work. |
| 275 | fb_info is only visible to the kernel. |
| 276 | </para> |
| 277 | |
| 278 | <para> |
| 279 | fb_var_screeninfo is used to describe the features of a video card |
| 280 | that are user defined. With fb_var_screeninfo, things such as |
| 281 | depth and the resolution may be defined. |
| 282 | </para> |
| 283 | |
| 284 | <para> |
| 285 | The next structure is fb_fix_screeninfo. This defines the |
| 286 | properties of a card that are created when a mode is set and can't |
| 287 | be changed otherwise. A good example of this is the start of the |
| 288 | frame buffer memory. This "locks" the address of the frame buffer |
| 289 | memory, so that it cannot be changed or moved. |
| 290 | </para> |
| 291 | |
| 292 | <para> |
| 293 | The last structure is fb_monospecs. In the old API, there was |
| 294 | little importance for fb_monospecs. This allowed for forbidden things |
| 295 | such as setting a mode of 800x600 on a fix frequency monitor. With |
| 296 | the new API, fb_monospecs prevents such things, and if used |
| 297 | correctly, can prevent a monitor from being cooked. fb_monospecs |
| 298 | will not be useful until kernels 2.5.x. |
| 299 | </para> |
| 300 | |
| 301 | <sect1><title>Frame Buffer Memory</title> |
Tomi Valkeinen | 19757fc | 2014-02-13 16:24:55 +0200 | [diff] [blame] | 302 | !Edrivers/video/fbdev/core/fbmem.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 303 | </sect1> |
| 304 | <!-- |
| 305 | <sect1><title>Frame Buffer Console</title> |
| 306 | X!Edrivers/video/console/fbcon.c |
| 307 | </sect1> |
| 308 | --> |
| 309 | <sect1><title>Frame Buffer Colormap</title> |
Tomi Valkeinen | 19757fc | 2014-02-13 16:24:55 +0200 | [diff] [blame] | 310 | !Edrivers/video/fbdev/core/fbcmap.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 311 | </sect1> |
| 312 | <!-- FIXME: |
| 313 | drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment |
| 314 | out until somebody adds docs. KAO |
| 315 | <sect1><title>Frame Buffer Generic Functions</title> |
| 316 | X!Idrivers/video/fbgen.c |
| 317 | </sect1> |
| 318 | KAO --> |
| 319 | <sect1><title>Frame Buffer Video Mode Database</title> |
Tomi Valkeinen | 19757fc | 2014-02-13 16:24:55 +0200 | [diff] [blame] | 320 | !Idrivers/video/fbdev/core/modedb.c |
| 321 | !Edrivers/video/fbdev/core/modedb.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 322 | </sect1> |
| 323 | <sect1><title>Frame Buffer Macintosh Video Mode Database</title> |
Tomi Valkeinen | f7018c2 | 2014-02-13 15:31:38 +0200 | [diff] [blame] | 324 | !Edrivers/video/fbdev/macmodes.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 325 | </sect1> |
| 326 | <sect1><title>Frame Buffer Fonts</title> |
| 327 | <para> |
Geert Uytterhoeven | ee89bd6 | 2013-06-09 11:46:43 +0200 | [diff] [blame] | 328 | Refer to the file lib/fonts/fonts.c for more information. |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 329 | </para> |
| 330 | <!-- FIXME: Removed for now since no structured comments in source |
Geert Uytterhoeven | ee89bd6 | 2013-06-09 11:46:43 +0200 | [diff] [blame] | 331 | X!Ilib/fonts/fonts.c |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 332 | --> |
| 333 | </sect1> |
| 334 | </chapter> |
| 335 | |
| 336 | <chapter id="input_subsystem"> |
| 337 | <title>Input Subsystem</title> |
Dmitry Torokhov | d69249f | 2009-11-16 22:12:20 -0800 | [diff] [blame] | 338 | <sect1><title>Input core</title> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 339 | !Iinclude/linux/input.h |
| 340 | !Edrivers/input/input.c |
| 341 | !Edrivers/input/ff-core.c |
| 342 | !Edrivers/input/ff-memless.c |
Dmitry Torokhov | d69249f | 2009-11-16 22:12:20 -0800 | [diff] [blame] | 343 | </sect1> |
Dmitry Torokhov | 69479f8 | 2010-12-09 01:08:26 -0800 | [diff] [blame] | 344 | <sect1><title>Multitouch Library</title> |
| 345 | !Iinclude/linux/input/mt.h |
| 346 | !Edrivers/input/input-mt.c |
| 347 | </sect1> |
Dmitry Torokhov | d69249f | 2009-11-16 22:12:20 -0800 | [diff] [blame] | 348 | <sect1><title>Polled input devices</title> |
| 349 | !Iinclude/linux/input-polldev.h |
| 350 | !Edrivers/input/input-polldev.c |
| 351 | </sect1> |
Masanari Iida | abaa5c2 | 2016-02-08 21:02:43 +0900 | [diff] [blame] | 352 | <sect1><title>Matrix keyboards/keypads</title> |
Dmitry Torokhov | d69249f | 2009-11-16 22:12:20 -0800 | [diff] [blame] | 353 | !Iinclude/linux/input/matrix_keypad.h |
| 354 | </sect1> |
Dmitry Torokhov | 36203c4 | 2009-12-04 10:22:23 -0800 | [diff] [blame] | 355 | <sect1><title>Sparse keymap support</title> |
| 356 | !Iinclude/linux/input/sparse-keymap.h |
| 357 | !Edrivers/input/sparse-keymap.c |
| 358 | </sect1> |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 359 | </chapter> |
| 360 | |
| 361 | <chapter id="spi"> |
| 362 | <title>Serial Peripheral Interface (SPI)</title> |
| 363 | <para> |
| 364 | SPI is the "Serial Peripheral Interface", widely used with |
| 365 | embedded systems because it is a simple and efficient |
| 366 | interface: basically a multiplexed shift register. |
| 367 | Its three signal wires hold a clock (SCK, often in the range |
| 368 | of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and |
| 369 | a "Master In, Slave Out" (MISO) data line. |
| 370 | SPI is a full duplex protocol; for each bit shifted out the |
| 371 | MOSI line (one per clock) another is shifted in on the MISO line. |
| 372 | Those bits are assembled into words of various sizes on the |
| 373 | way to and from system memory. |
| 374 | An additional chipselect line is usually active-low (nCS); |
| 375 | four signals are normally used for each peripheral, plus |
| 376 | sometimes an interrupt. |
| 377 | </para> |
| 378 | <para> |
| 379 | The SPI bus facilities listed here provide a generalized |
| 380 | interface to declare SPI busses and devices, manage them |
| 381 | according to the standard Linux driver model, and perform |
| 382 | input/output operations. |
| 383 | At this time, only "master" side interfaces are supported, |
| 384 | where Linux talks to SPI peripherals and does not implement |
| 385 | such a peripheral itself. |
| 386 | (Interfaces to support implementing SPI slaves would |
| 387 | necessarily look different.) |
| 388 | </para> |
| 389 | <para> |
| 390 | The programming interface is structured around two kinds of driver, |
| 391 | and two kinds of device. |
| 392 | A "Controller Driver" abstracts the controller hardware, which may |
| 393 | be as simple as a set of GPIO pins or as complex as a pair of FIFOs |
| 394 | connected to dual DMA engines on the other side of the SPI shift |
| 395 | register (maximizing throughput). Such drivers bridge between |
| 396 | whatever bus they sit on (often the platform bus) and SPI, and |
| 397 | expose the SPI side of their device as a |
| 398 | <structname>struct spi_master</structname>. |
| 399 | SPI devices are children of that master, represented as a |
| 400 | <structname>struct spi_device</structname> and manufactured from |
| 401 | <structname>struct spi_board_info</structname> descriptors which |
| 402 | are usually provided by board-specific initialization code. |
| 403 | A <structname>struct spi_driver</structname> is called a |
| 404 | "Protocol Driver", and is bound to a spi_device using normal |
| 405 | driver model calls. |
| 406 | </para> |
| 407 | <para> |
| 408 | The I/O model is a set of queued messages. Protocol drivers |
| 409 | submit one or more <structname>struct spi_message</structname> |
| 410 | objects, which are processed and completed asynchronously. |
| 411 | (There are synchronous wrappers, however.) Messages are |
| 412 | built from one or more <structname>struct spi_transfer</structname> |
| 413 | objects, each of which wraps a full duplex SPI transfer. |
| 414 | A variety of protocol tweaking options are needed, because |
| 415 | different chips adopt very different policies for how they |
| 416 | use the bits transferred with SPI. |
| 417 | </para> |
| 418 | !Iinclude/linux/spi/spi.h |
| 419 | !Fdrivers/spi/spi.c spi_register_board_info |
| 420 | !Edrivers/spi/spi.c |
| 421 | </chapter> |
| 422 | |
| 423 | <chapter id="i2c"> |
| 424 | <title>I<superscript>2</superscript>C and SMBus Subsystem</title> |
| 425 | |
| 426 | <para> |
| 427 | I<superscript>2</superscript>C (or without fancy typography, "I2C") |
| 428 | is an acronym for the "Inter-IC" bus, a simple bus protocol which is |
| 429 | widely used where low data rate communications suffice. |
| 430 | Since it's also a licensed trademark, some vendors use another |
| 431 | name (such as "Two-Wire Interface", TWI) for the same bus. |
| 432 | I2C only needs two signals (SCL for clock, SDA for data), conserving |
| 433 | board real estate and minimizing signal quality issues. |
| 434 | Most I2C devices use seven bit addresses, and bus speeds of up |
| 435 | to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet |
| 436 | found wide use. |
| 437 | I2C is a multi-master bus; open drain signaling is used to |
| 438 | arbitrate between masters, as well as to handshake and to |
| 439 | synchronize clocks from slower clients. |
| 440 | </para> |
| 441 | |
| 442 | <para> |
| 443 | The Linux I2C programming interfaces support only the master |
| 444 | side of bus interactions, not the slave side. |
| 445 | The programming interface is structured around two kinds of driver, |
| 446 | and two kinds of device. |
| 447 | An I2C "Adapter Driver" abstracts the controller hardware; it binds |
| 448 | to a physical device (perhaps a PCI device or platform_device) and |
| 449 | exposes a <structname>struct i2c_adapter</structname> representing |
| 450 | each I2C bus segment it manages. |
| 451 | On each I2C bus segment will be I2C devices represented by a |
| 452 | <structname>struct i2c_client</structname>. Those devices will |
| 453 | be bound to a <structname>struct i2c_driver</structname>, |
| 454 | which should follow the standard Linux driver model. |
| 455 | (At this writing, a legacy model is more widely used.) |
| 456 | There are functions to perform various I2C protocol operations; at |
| 457 | this writing all such functions are usable only from task context. |
| 458 | </para> |
| 459 | |
| 460 | <para> |
| 461 | The System Management Bus (SMBus) is a sibling protocol. Most SMBus |
| 462 | systems are also I2C conformant. The electrical constraints are |
| 463 | tighter for SMBus, and it standardizes particular protocol messages |
| 464 | and idioms. Controllers that support I2C can also support most |
| 465 | SMBus operations, but SMBus controllers don't support all the protocol |
| 466 | options that an I2C controller will. |
| 467 | There are functions to perform various SMBus protocol operations, |
| 468 | either using I2C primitives or by issuing SMBus commands to |
| 469 | i2c_adapter devices which don't support those I2C operations. |
| 470 | </para> |
| 471 | |
| 472 | !Iinclude/linux/i2c.h |
| 473 | !Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info |
| 474 | !Edrivers/i2c/i2c-core.c |
| 475 | </chapter> |
| 476 | |
Carlos Chinea | a4ac73a | 2010-04-29 13:19:06 +0300 | [diff] [blame] | 477 | <chapter id="hsi"> |
| 478 | <title>High Speed Synchronous Serial Interface (HSI)</title> |
| 479 | |
| 480 | <para> |
| 481 | High Speed Synchronous Serial Interface (HSI) is a |
| 482 | serial interface mainly used for connecting application |
| 483 | engines (APE) with cellular modem engines (CMT) in cellular |
| 484 | handsets. |
| 485 | |
| 486 | HSI provides multiplexing for up to 16 logical channels, |
| 487 | low-latency and full duplex communication. |
| 488 | </para> |
| 489 | |
| 490 | !Iinclude/linux/hsi/hsi.h |
Andrew F. Davis | e01957a | 2016-06-14 11:13:04 -0500 | [diff] [blame] | 491 | !Edrivers/hsi/hsi_core.c |
Carlos Chinea | a4ac73a | 2010-04-29 13:19:06 +0300 | [diff] [blame] | 492 | </chapter> |
| 493 | |
Thierry Reding | 6e146f5 | 2015-07-27 12:00:23 +0200 | [diff] [blame] | 494 | <chapter id="pwm"> |
| 495 | <title>Pulse-Width Modulation (PWM)</title> |
| 496 | <para> |
| 497 | Pulse-width modulation is a modulation technique primarily used to |
| 498 | control power supplied to electrical devices. |
| 499 | </para> |
| 500 | <para> |
| 501 | The PWM framework provides an abstraction for providers and consumers |
| 502 | of PWM signals. A controller that provides one or more PWM signals is |
| 503 | registered as <structname>struct pwm_chip</structname>. Providers are |
| 504 | expected to embed this structure in a driver-specific structure. This |
| 505 | structure contains fields that describe a particular chip. |
| 506 | </para> |
| 507 | <para> |
| 508 | A chip exposes one or more PWM signal sources, each of which exposed |
| 509 | as a <structname>struct pwm_device</structname>. Operations can be |
| 510 | performed on PWM devices to control the period, duty cycle, polarity |
| 511 | and active state of the signal. |
| 512 | </para> |
| 513 | <para> |
| 514 | Note that PWM devices are exclusive resources: they can always only be |
| 515 | used by one consumer at a time. |
| 516 | </para> |
| 517 | !Iinclude/linux/pwm.h |
| 518 | !Edrivers/pwm/core.c |
| 519 | </chapter> |
| 520 | |
Randy Dunlap | f7f84f3 | 2009-02-22 12:15:45 -0800 | [diff] [blame] | 521 | </book> |