From 47cb398dd75a9faa89d0617b55d4cf537935b731 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:02:50 -0600 Subject: Docs: sphinxify device-drivers.tmpl Perform a basic sphinx conversion of the device-drivers docbook and move it to its own directory. Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/device-drivers.tmpl | 521 ------------------------------ 2 files changed, 1 insertion(+), 522 deletions(-) delete mode 100644 Documentation/DocBook/device-drivers.tmpl (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a91c96522379..5fbfb7273f38 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := z8530book.xml device-drivers.xml \ +DOCBOOKS := z8530book.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl deleted file mode 100644 index 9c10030eb2be..000000000000 --- a/Documentation/DocBook/device-drivers.tmpl +++ /dev/null @@ -1,521 +0,0 @@ - - - - - - Linux Device Drivers - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Driver Basics - Driver Entry and Exit points -!Iinclude/linux/init.h - - - Atomic and pointer manipulation -!Iarch/x86/include/asm/atomic.h - - - Delaying, scheduling, and timer routines -!Iinclude/linux/sched.h -!Ekernel/sched/core.c -!Ikernel/sched/cpupri.c -!Ikernel/sched/fair.c -!Iinclude/linux/completion.h -!Ekernel/time/timer.c - - Wait queues and Wake events -!Iinclude/linux/wait.h -!Ekernel/sched/wait.c - - High-resolution timers -!Iinclude/linux/ktime.h -!Iinclude/linux/hrtimer.h -!Ekernel/time/hrtimer.c - - Workqueues and Kevents -!Iinclude/linux/workqueue.h -!Ekernel/workqueue.c - - Internal Functions -!Ikernel/exit.c -!Ikernel/signal.c -!Iinclude/linux/kthread.h -!Ekernel/kthread.c - - - Kernel objects manipulation - -!Elib/kobject.c - - - Kernel utility functions -!Iinclude/linux/kernel.h -!Ekernel/printk/printk.c -!Ekernel/panic.c -!Ekernel/sys.c -!Ekernel/rcu/srcu.c -!Ekernel/rcu/tree.c -!Ekernel/rcu/tree_plugin.h -!Ekernel/rcu/update.c - - - Device Resource Management -!Edrivers/base/devres.c - - - - - - Device drivers infrastructure - The Basic Device Driver-Model Structures -!Iinclude/linux/device.h - - Device Drivers Base -!Idrivers/base/init.c -!Edrivers/base/driver.c -!Edrivers/base/core.c -!Edrivers/base/syscore.c -!Edrivers/base/class.c -!Idrivers/base/node.c -!Edrivers/base/firmware_class.c -!Edrivers/base/transport_class.c - -!Edrivers/base/dd.c - -!Iinclude/linux/platform_device.h -!Edrivers/base/platform.c -!Edrivers/base/bus.c - - - Buffer Sharing and Synchronization - - The dma-buf subsystem provides the framework for sharing buffers - for hardware (DMA) access across multiple device drivers and - subsystems, and for synchronizing asynchronous hardware access. - - - This is used, for example, by drm "prime" multi-GPU support, but - is of course not limited to GPU use cases. - - - The three main components of this are: (1) dma-buf, representing - a sg_table and exposed to userspace as a file descriptor to allow - passing between devices, (2) fence, which provides a mechanism - to signal when one device as finished access, and (3) reservation, - which manages the shared or exclusive fence(s) associated with - the buffer. - - dma-buf -!Edrivers/dma-buf/dma-buf.c -!Iinclude/linux/dma-buf.h - - reservation -!Pdrivers/dma-buf/reservation.c Reservation Object Overview -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h - - fence -!Edrivers/dma-buf/fence.c -!Iinclude/linux/fence.h -!Edrivers/dma-buf/seqno-fence.c -!Iinclude/linux/seqno-fence.h -!Edrivers/dma-buf/fence-array.c -!Iinclude/linux/fence-array.h -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h -!Edrivers/dma-buf/sync_file.c -!Iinclude/linux/sync_file.h - - - Device Drivers DMA Management -!Edrivers/base/dma-coherent.c -!Edrivers/base/dma-mapping.c - - Device Drivers Power Management -!Edrivers/base/power/main.c - - Device Drivers ACPI Support - -!Edrivers/acpi/scan.c -!Idrivers/acpi/scan.c - - - Device drivers PnP support -!Idrivers/pnp/core.c - -!Edrivers/pnp/card.c -!Idrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - - Userspace IO devices -!Edrivers/uio/uio.c -!Iinclude/linux/uio_driver.h - - - - - Parallel Port Devices -!Iinclude/linux/parport.h -!Edrivers/parport/ieee1284.c -!Edrivers/parport/share.c -!Idrivers/parport/daisy.c - - - - Message-based devices - Fusion message devices -!Edrivers/message/fusion/mptbase.c -!Idrivers/message/fusion/mptbase.c -!Edrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptctl.c -!Idrivers/message/fusion/mptspi.c -!Idrivers/message/fusion/mptfc.c -!Idrivers/message/fusion/mptlan.c - - - - - Sound Devices -!Iinclude/sound/core.h -!Esound/sound_core.c -!Iinclude/sound/pcm.h -!Esound/core/pcm.c -!Esound/core/device.c -!Esound/core/info.c -!Esound/core/rawmidi.c -!Esound/core/sound.c -!Esound/core/memory.c -!Esound/core/pcm_memory.c -!Esound/core/init.c -!Esound/core/isadma.c -!Esound/core/control.c -!Esound/core/pcm_lib.c -!Esound/core/hwdep.c -!Esound/core/pcm_native.c -!Esound/core/memalloc.c - - - - - - 16x50 UART Driver -!Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250/8250_core.c - - - - Frame Buffer Library - - - The frame buffer drivers depend heavily on four data structures. - These structures are declared in include/linux/fb.h. They are - fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. - The last three can be made available to and from userland. - - - - fb_info defines the current state of a particular video card. - Inside fb_info, there exists a fb_ops structure which is a - collection of needed functions to make fbdev and fbcon work. - fb_info is only visible to the kernel. - - - - fb_var_screeninfo is used to describe the features of a video card - that are user defined. With fb_var_screeninfo, things such as - depth and the resolution may be defined. - - - - The next structure is fb_fix_screeninfo. This defines the - properties of a card that are created when a mode is set and can't - be changed otherwise. A good example of this is the start of the - frame buffer memory. This "locks" the address of the frame buffer - memory, so that it cannot be changed or moved. - - - - The last structure is fb_monospecs. In the old API, there was - little importance for fb_monospecs. This allowed for forbidden things - such as setting a mode of 800x600 on a fix frequency monitor. With - the new API, fb_monospecs prevents such things, and if used - correctly, can prevent a monitor from being cooked. fb_monospecs - will not be useful until kernels 2.5.x. - - - Frame Buffer Memory -!Edrivers/video/fbdev/core/fbmem.c - - - Frame Buffer Colormap -!Edrivers/video/fbdev/core/fbcmap.c - - - Frame Buffer Video Mode Database -!Idrivers/video/fbdev/core/modedb.c -!Edrivers/video/fbdev/core/modedb.c - - Frame Buffer Macintosh Video Mode Database -!Edrivers/video/fbdev/macmodes.c - - Frame Buffer Fonts - - Refer to the file lib/fonts/fonts.c for more information. - - - - - - - Input Subsystem - Input core -!Iinclude/linux/input.h -!Edrivers/input/input.c -!Edrivers/input/ff-core.c -!Edrivers/input/ff-memless.c - - Multitouch Library -!Iinclude/linux/input/mt.h -!Edrivers/input/input-mt.c - - Polled input devices -!Iinclude/linux/input-polldev.h -!Edrivers/input/input-polldev.c - - Matrix keyboards/keypads -!Iinclude/linux/input/matrix_keypad.h - - Sparse keymap support -!Iinclude/linux/input/sparse-keymap.h -!Edrivers/input/sparse-keymap.c - - - - - Serial Peripheral Interface (SPI) - - SPI is the "Serial Peripheral Interface", widely used with - embedded systems because it is a simple and efficient - interface: basically a multiplexed shift register. - Its three signal wires hold a clock (SCK, often in the range - of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and - a "Master In, Slave Out" (MISO) data line. - SPI is a full duplex protocol; for each bit shifted out the - MOSI line (one per clock) another is shifted in on the MISO line. - Those bits are assembled into words of various sizes on the - way to and from system memory. - An additional chipselect line is usually active-low (nCS); - four signals are normally used for each peripheral, plus - sometimes an interrupt. - - - The SPI bus facilities listed here provide a generalized - interface to declare SPI busses and devices, manage them - according to the standard Linux driver model, and perform - input/output operations. - At this time, only "master" side interfaces are supported, - where Linux talks to SPI peripherals and does not implement - such a peripheral itself. - (Interfaces to support implementing SPI slaves would - necessarily look different.) - - - The programming interface is structured around two kinds of driver, - and two kinds of device. - A "Controller Driver" abstracts the controller hardware, which may - be as simple as a set of GPIO pins or as complex as a pair of FIFOs - connected to dual DMA engines on the other side of the SPI shift - register (maximizing throughput). Such drivers bridge between - whatever bus they sit on (often the platform bus) and SPI, and - expose the SPI side of their device as a - struct spi_master. - SPI devices are children of that master, represented as a - struct spi_device and manufactured from - struct spi_board_info descriptors which - are usually provided by board-specific initialization code. - A struct spi_driver is called a - "Protocol Driver", and is bound to a spi_device using normal - driver model calls. - - - The I/O model is a set of queued messages. Protocol drivers - submit one or more struct spi_message - objects, which are processed and completed asynchronously. - (There are synchronous wrappers, however.) Messages are - built from one or more struct spi_transfer - objects, each of which wraps a full duplex SPI transfer. - A variety of protocol tweaking options are needed, because - different chips adopt very different policies for how they - use the bits transferred with SPI. - -!Iinclude/linux/spi/spi.h -!Fdrivers/spi/spi.c spi_register_board_info -!Edrivers/spi/spi.c - - - - I<superscript>2</superscript>C and SMBus Subsystem - - - I2C (or without fancy typography, "I2C") - is an acronym for the "Inter-IC" bus, a simple bus protocol which is - widely used where low data rate communications suffice. - Since it's also a licensed trademark, some vendors use another - name (such as "Two-Wire Interface", TWI) for the same bus. - I2C only needs two signals (SCL for clock, SDA for data), conserving - board real estate and minimizing signal quality issues. - Most I2C devices use seven bit addresses, and bus speeds of up - to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet - found wide use. - I2C is a multi-master bus; open drain signaling is used to - arbitrate between masters, as well as to handshake and to - synchronize clocks from slower clients. - - - - The Linux I2C programming interfaces support only the master - side of bus interactions, not the slave side. - The programming interface is structured around two kinds of driver, - and two kinds of device. - An I2C "Adapter Driver" abstracts the controller hardware; it binds - to a physical device (perhaps a PCI device or platform_device) and - exposes a struct i2c_adapter representing - each I2C bus segment it manages. - On each I2C bus segment will be I2C devices represented by a - struct i2c_client. Those devices will - be bound to a struct i2c_driver, - which should follow the standard Linux driver model. - (At this writing, a legacy model is more widely used.) - There are functions to perform various I2C protocol operations; at - this writing all such functions are usable only from task context. - - - - The System Management Bus (SMBus) is a sibling protocol. Most SMBus - systems are also I2C conformant. The electrical constraints are - tighter for SMBus, and it standardizes particular protocol messages - and idioms. Controllers that support I2C can also support most - SMBus operations, but SMBus controllers don't support all the protocol - options that an I2C controller will. - There are functions to perform various SMBus protocol operations, - either using I2C primitives or by issuing SMBus commands to - i2c_adapter devices which don't support those I2C operations. - - -!Iinclude/linux/i2c.h -!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info -!Edrivers/i2c/i2c-core.c - - - - High Speed Synchronous Serial Interface (HSI) - - - High Speed Synchronous Serial Interface (HSI) is a - serial interface mainly used for connecting application - engines (APE) with cellular modem engines (CMT) in cellular - handsets. - - HSI provides multiplexing for up to 16 logical channels, - low-latency and full duplex communication. - - -!Iinclude/linux/hsi/hsi.h -!Edrivers/hsi/hsi_core.c - - - - Pulse-Width Modulation (PWM) - - Pulse-width modulation is a modulation technique primarily used to - control power supplied to electrical devices. - - - The PWM framework provides an abstraction for providers and consumers - of PWM signals. A controller that provides one or more PWM signals is - registered as struct pwm_chip. Providers are - expected to embed this structure in a driver-specific structure. This - structure contains fields that describe a particular chip. - - - A chip exposes one or more PWM signal sources, each of which exposed - as a struct pwm_device. Operations can be - performed on PWM devices to control the period, duty cycle, polarity - and active state of the signal. - - - Note that PWM devices are exclusive resources: they can always only be - used by one consumer at a time. - -!Iinclude/linux/pwm.h -!Edrivers/pwm/core.c - - - -- cgit v1.2.3