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 ------------------------ Documentation/driver-api/drivers.rst | 654 ++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + 4 files changed, 656 insertions(+), 522 deletions(-) delete mode 100644 Documentation/DocBook/device-drivers.tmpl create mode 100644 Documentation/driver-api/drivers.rst (limited to 'Documentation') 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 - - - diff --git a/Documentation/driver-api/drivers.rst b/Documentation/driver-api/drivers.rst new file mode 100644 index 000000000000..17f99d441b52 --- /dev/null +++ b/Documentation/driver-api/drivers.rst @@ -0,0 +1,654 @@ +==================== +Linux Device Drivers +==================== + +Driver Basics +============= + +Driver Entry and Exit points +---------------------------- + +.. kernel-doc:: include/linux/init.h + :internal: + +Atomic and pointer manipulation +------------------------------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + +Delaying, scheduling, and timer routines +---------------------------------------- + +.. kernel-doc:: include/linux/sched.h + :internal: + +.. kernel-doc:: kernel/sched/core.c + :export: + +.. kernel-doc:: kernel/sched/cpupri.c + :internal: + +.. kernel-doc:: kernel/sched/fair.c + :internal: + +.. kernel-doc:: include/linux/completion.h + :internal: + +.. kernel-doc:: kernel/time/timer.c + :export: + +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + +High-resolution timers +---------------------- + +.. kernel-doc:: include/linux/ktime.h + :internal: + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: + +Workqueues and Kevents +---------------------- + +.. kernel-doc:: include/linux/workqueue.h + :internal: + +.. kernel-doc:: kernel/workqueue.c + :export: + +Internal Functions +------------------ + +.. kernel-doc:: kernel/exit.c + :internal: + +.. kernel-doc:: kernel/signal.c + :internal: + +.. kernel-doc:: include/linux/kthread.h + :internal: + +.. kernel-doc:: kernel/kthread.c + :export: + +Kernel objects manipulation +--------------------------- + +.. kernel-doc:: lib/kobject.c + :export: + +Kernel utility functions +------------------------ + +.. kernel-doc:: include/linux/kernel.h + :internal: + +.. kernel-doc:: kernel/printk/printk.c + :export: + +.. kernel-doc:: kernel/panic.c + :export: + +.. kernel-doc:: kernel/sys.c + :export: + +.. kernel-doc:: kernel/rcu/srcu.c + :export: + +.. kernel-doc:: kernel/rcu/tree.c + :export: + +.. kernel-doc:: kernel/rcu/tree_plugin.h + :export: + +.. kernel-doc:: kernel/rcu/update.c + :export: + +Device Resource Management +-------------------------- + +.. kernel-doc:: drivers/base/devres.c + :export: + +Device drivers infrastructure +============================= + +The Basic Device Driver-Model Structures +---------------------------------------- + +.. kernel-doc:: include/linux/device.h + :internal: + +Device Drivers Base +------------------- + +.. kernel-doc:: drivers/base/init.c + :internal: + +.. kernel-doc:: drivers/base/driver.c + :export: + +.. kernel-doc:: drivers/base/core.c + :export: + +.. kernel-doc:: drivers/base/syscore.c + :export: + +.. kernel-doc:: drivers/base/class.c + :export: + +.. kernel-doc:: drivers/base/node.c + :internal: + +.. kernel-doc:: drivers/base/firmware_class.c + :export: + +.. kernel-doc:: drivers/base/transport_class.c + :export: + +.. kernel-doc:: drivers/base/dd.c + :export: + +.. kernel-doc:: include/linux/platform_device.h + :internal: + +.. kernel-doc:: drivers/base/platform.c + :export: + +.. kernel-doc:: drivers/base/bus.c + :export: + +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 +~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :export: + +.. kernel-doc:: include/linux/dma-buf.h + :internal: + +reservation +~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/reservation.c + :doc: Reservation Object Overview + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +fence +~~~~~ + +.. kernel-doc:: drivers/dma-buf/fence.c + :export: + +.. kernel-doc:: include/linux/fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/seqno-fence.c + :export: + +.. kernel-doc:: include/linux/seqno-fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/fence-array.c + :export: + +.. kernel-doc:: include/linux/fence-array.h + :internal: + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +.. kernel-doc:: drivers/dma-buf/sync_file.c + :export: + +.. kernel-doc:: include/linux/sync_file.h + :internal: + +Device Drivers DMA Management +----------------------------- + +.. kernel-doc:: drivers/base/dma-coherent.c + :export: + +.. kernel-doc:: drivers/base/dma-mapping.c + :export: + +Device Drivers Power Management +------------------------------- + +.. kernel-doc:: drivers/base/power/main.c + :export: + +Device Drivers ACPI Support +--------------------------- + +.. kernel-doc:: drivers/acpi/scan.c + :export: + +.. kernel-doc:: drivers/acpi/scan.c + :internal: + +Device drivers PnP support +-------------------------- + +.. kernel-doc:: drivers/pnp/core.c + :internal: + +.. kernel-doc:: drivers/pnp/card.c + :export: + +.. kernel-doc:: drivers/pnp/driver.c + :internal: + +.. kernel-doc:: drivers/pnp/manager.c + :export: + +.. kernel-doc:: drivers/pnp/support.c + :export: + +Userspace IO devices +-------------------- + +.. kernel-doc:: drivers/uio/uio.c + :export: + +.. kernel-doc:: include/linux/uio_driver.h + :internal: + +Parallel Port Devices +===================== + +.. kernel-doc:: include/linux/parport.h + :internal: + +.. kernel-doc:: drivers/parport/ieee1284.c + :export: + +.. kernel-doc:: drivers/parport/share.c + :export: + +.. kernel-doc:: drivers/parport/daisy.c + :internal: + +Message-based devices +===================== + +Fusion message devices +---------------------- + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptctl.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptspi.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptfc.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptlan.c + :internal: + +Sound Devices +============= + +.. kernel-doc:: include/sound/core.h + :internal: + +.. kernel-doc:: sound/sound_core.c + :export: + +.. kernel-doc:: include/sound/pcm.h + :internal: + +.. kernel-doc:: sound/core/pcm.c + :export: + +.. kernel-doc:: sound/core/device.c + :export: + +.. kernel-doc:: sound/core/info.c + :export: + +.. kernel-doc:: sound/core/rawmidi.c + :export: + +.. kernel-doc:: sound/core/sound.c + :export: + +.. kernel-doc:: sound/core/memory.c + :export: + +.. kernel-doc:: sound/core/pcm_memory.c + :export: + +.. kernel-doc:: sound/core/init.c + :export: + +.. kernel-doc:: sound/core/isadma.c + :export: + +.. kernel-doc:: sound/core/control.c + :export: + +.. kernel-doc:: sound/core/pcm_lib.c + :export: + +.. kernel-doc:: sound/core/hwdep.c + :export: + +.. kernel-doc:: sound/core/pcm_native.c + :export: + +.. kernel-doc:: sound/core/memalloc.c + :export: + +16x50 UART Driver +================= + +.. kernel-doc:: drivers/tty/serial/serial_core.c + :export: + +.. kernel-doc:: drivers/tty/serial/8250/8250_core.c + :export: + +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 +------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbmem.c + :export: + +Frame Buffer Colormap +--------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c + :export: + +Frame Buffer Video Mode Database +-------------------------------- + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :internal: + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :export: + +Frame Buffer Macintosh Video Mode Database +------------------------------------------ + +.. kernel-doc:: drivers/video/fbdev/macmodes.c + :export: + +Frame Buffer Fonts +------------------ + +Refer to the file lib/fonts/fonts.c for more information. + +Input Subsystem +=============== + +Input core +---------- + +.. kernel-doc:: include/linux/input.h + :internal: + +.. kernel-doc:: drivers/input/input.c + :export: + +.. kernel-doc:: drivers/input/ff-core.c + :export: + +.. kernel-doc:: drivers/input/ff-memless.c + :export: + +Multitouch Library +------------------ + +.. kernel-doc:: include/linux/input/mt.h + :internal: + +.. kernel-doc:: drivers/input/input-mt.c + :export: + +Polled input devices +-------------------- + +.. kernel-doc:: include/linux/input-polldev.h + :internal: + +.. kernel-doc:: drivers/input/input-polldev.c + :export: + +Matrix keyboards/keypads +------------------------ + +.. kernel-doc:: include/linux/input/matrix_keypad.h + :internal: + +Sparse keymap support +--------------------- + +.. kernel-doc:: include/linux/input/sparse-keymap.h + :internal: + +.. kernel-doc:: drivers/input/sparse-keymap.c + :export: + +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 :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`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 :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`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. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: + +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (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 +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`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. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: + +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. + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + +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 :c:type:`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 :c:type:`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. + +.. kernel-doc:: include/linux/pwm.h + :internal: + +.. kernel-doc:: drivers/pwm/core.c + :export: diff --git a/Documentation/index.rst b/Documentation/index.rst index 05eded59820e..0d6992b897c8 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,7 @@ Contents: kernel-documentation dev-tools/tools + driver-api/drivers media/index gpu/index -- cgit v1.2.3 From dcec3c8c9aea9e779c59f420465381c0f3322913 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:17:32 -0600 Subject: docs: split up the driver book We don't need to keep it as a single large file anymore; split it up so that it is easier to manage and the individual sections can be read directly as plain files. Signed-off-by: Jonathan Corbet --- Documentation/driver-api/basics.rst | 120 +++++ Documentation/driver-api/drivers.rst | 654 ------------------------- Documentation/driver-api/frame-buffer.rst | 62 +++ Documentation/driver-api/index.rst | 24 + Documentation/driver-api/infrastructure.rst | 169 +++++++ Documentation/driver-api/input.rst | 51 ++ Documentation/driver-api/message-based.rst | 30 ++ Documentation/driver-api/miscellaneous.rst | 50 ++ Documentation/driver-api/serial-interfaces.rst | 115 +++++ Documentation/driver-api/sound.rst | 54 ++ Documentation/index.rst | 2 +- 11 files changed, 676 insertions(+), 655 deletions(-) create mode 100644 Documentation/driver-api/basics.rst delete mode 100644 Documentation/driver-api/drivers.rst create mode 100644 Documentation/driver-api/frame-buffer.rst create mode 100644 Documentation/driver-api/index.rst create mode 100644 Documentation/driver-api/infrastructure.rst create mode 100644 Documentation/driver-api/input.rst create mode 100644 Documentation/driver-api/message-based.rst create mode 100644 Documentation/driver-api/miscellaneous.rst create mode 100644 Documentation/driver-api/serial-interfaces.rst create mode 100644 Documentation/driver-api/sound.rst (limited to 'Documentation') diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst new file mode 100644 index 000000000000..935b9b8d456c --- /dev/null +++ b/Documentation/driver-api/basics.rst @@ -0,0 +1,120 @@ +Driver Basics +============= + +Driver Entry and Exit points +---------------------------- + +.. kernel-doc:: include/linux/init.h + :internal: + +Atomic and pointer manipulation +------------------------------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + +Delaying, scheduling, and timer routines +---------------------------------------- + +.. kernel-doc:: include/linux/sched.h + :internal: + +.. kernel-doc:: kernel/sched/core.c + :export: + +.. kernel-doc:: kernel/sched/cpupri.c + :internal: + +.. kernel-doc:: kernel/sched/fair.c + :internal: + +.. kernel-doc:: include/linux/completion.h + :internal: + +.. kernel-doc:: kernel/time/timer.c + :export: + +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + +High-resolution timers +---------------------- + +.. kernel-doc:: include/linux/ktime.h + :internal: + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: + +Workqueues and Kevents +---------------------- + +.. kernel-doc:: include/linux/workqueue.h + :internal: + +.. kernel-doc:: kernel/workqueue.c + :export: + +Internal Functions +------------------ + +.. kernel-doc:: kernel/exit.c + :internal: + +.. kernel-doc:: kernel/signal.c + :internal: + +.. kernel-doc:: include/linux/kthread.h + :internal: + +.. kernel-doc:: kernel/kthread.c + :export: + +Kernel objects manipulation +--------------------------- + +.. kernel-doc:: lib/kobject.c + :export: + +Kernel utility functions +------------------------ + +.. kernel-doc:: include/linux/kernel.h + :internal: + +.. kernel-doc:: kernel/printk/printk.c + :export: + +.. kernel-doc:: kernel/panic.c + :export: + +.. kernel-doc:: kernel/sys.c + :export: + +.. kernel-doc:: kernel/rcu/srcu.c + :export: + +.. kernel-doc:: kernel/rcu/tree.c + :export: + +.. kernel-doc:: kernel/rcu/tree_plugin.h + :export: + +.. kernel-doc:: kernel/rcu/update.c + :export: + +Device Resource Management +-------------------------- + +.. kernel-doc:: drivers/base/devres.c + :export: + diff --git a/Documentation/driver-api/drivers.rst b/Documentation/driver-api/drivers.rst deleted file mode 100644 index 17f99d441b52..000000000000 --- a/Documentation/driver-api/drivers.rst +++ /dev/null @@ -1,654 +0,0 @@ -==================== -Linux Device Drivers -==================== - -Driver Basics -============= - -Driver Entry and Exit points ----------------------------- - -.. kernel-doc:: include/linux/init.h - :internal: - -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - -Delaying, scheduling, and timer routines ----------------------------------------- - -.. kernel-doc:: include/linux/sched.h - :internal: - -.. kernel-doc:: kernel/sched/core.c - :export: - -.. kernel-doc:: kernel/sched/cpupri.c - :internal: - -.. kernel-doc:: kernel/sched/fair.c - :internal: - -.. kernel-doc:: include/linux/completion.h - :internal: - -.. kernel-doc:: kernel/time/timer.c - :export: - -Wait queues and Wake events ---------------------------- - -.. kernel-doc:: include/linux/wait.h - :internal: - -.. kernel-doc:: kernel/sched/wait.c - :export: - -High-resolution timers ----------------------- - -.. kernel-doc:: include/linux/ktime.h - :internal: - -.. kernel-doc:: include/linux/hrtimer.h - :internal: - -.. kernel-doc:: kernel/time/hrtimer.c - :export: - -Workqueues and Kevents ----------------------- - -.. kernel-doc:: include/linux/workqueue.h - :internal: - -.. kernel-doc:: kernel/workqueue.c - :export: - -Internal Functions ------------------- - -.. kernel-doc:: kernel/exit.c - :internal: - -.. kernel-doc:: kernel/signal.c - :internal: - -.. kernel-doc:: include/linux/kthread.h - :internal: - -.. kernel-doc:: kernel/kthread.c - :export: - -Kernel objects manipulation ---------------------------- - -.. kernel-doc:: lib/kobject.c - :export: - -Kernel utility functions ------------------------- - -.. kernel-doc:: include/linux/kernel.h - :internal: - -.. kernel-doc:: kernel/printk/printk.c - :export: - -.. kernel-doc:: kernel/panic.c - :export: - -.. kernel-doc:: kernel/sys.c - :export: - -.. kernel-doc:: kernel/rcu/srcu.c - :export: - -.. kernel-doc:: kernel/rcu/tree.c - :export: - -.. kernel-doc:: kernel/rcu/tree_plugin.h - :export: - -.. kernel-doc:: kernel/rcu/update.c - :export: - -Device Resource Management --------------------------- - -.. kernel-doc:: drivers/base/devres.c - :export: - -Device drivers infrastructure -============================= - -The Basic Device Driver-Model Structures ----------------------------------------- - -.. kernel-doc:: include/linux/device.h - :internal: - -Device Drivers Base -------------------- - -.. kernel-doc:: drivers/base/init.c - :internal: - -.. kernel-doc:: drivers/base/driver.c - :export: - -.. kernel-doc:: drivers/base/core.c - :export: - -.. kernel-doc:: drivers/base/syscore.c - :export: - -.. kernel-doc:: drivers/base/class.c - :export: - -.. kernel-doc:: drivers/base/node.c - :internal: - -.. kernel-doc:: drivers/base/firmware_class.c - :export: - -.. kernel-doc:: drivers/base/transport_class.c - :export: - -.. kernel-doc:: drivers/base/dd.c - :export: - -.. kernel-doc:: include/linux/platform_device.h - :internal: - -.. kernel-doc:: drivers/base/platform.c - :export: - -.. kernel-doc:: drivers/base/bus.c - :export: - -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 -~~~~~~~ - -.. kernel-doc:: drivers/dma-buf/dma-buf.c - :export: - -.. kernel-doc:: include/linux/dma-buf.h - :internal: - -reservation -~~~~~~~~~~~ - -.. kernel-doc:: drivers/dma-buf/reservation.c - :doc: Reservation Object Overview - -.. kernel-doc:: drivers/dma-buf/reservation.c - :export: - -.. kernel-doc:: include/linux/reservation.h - :internal: - -fence -~~~~~ - -.. kernel-doc:: drivers/dma-buf/fence.c - :export: - -.. kernel-doc:: include/linux/fence.h - :internal: - -.. kernel-doc:: drivers/dma-buf/seqno-fence.c - :export: - -.. kernel-doc:: include/linux/seqno-fence.h - :internal: - -.. kernel-doc:: drivers/dma-buf/fence-array.c - :export: - -.. kernel-doc:: include/linux/fence-array.h - :internal: - -.. kernel-doc:: drivers/dma-buf/reservation.c - :export: - -.. kernel-doc:: include/linux/reservation.h - :internal: - -.. kernel-doc:: drivers/dma-buf/sync_file.c - :export: - -.. kernel-doc:: include/linux/sync_file.h - :internal: - -Device Drivers DMA Management ------------------------------ - -.. kernel-doc:: drivers/base/dma-coherent.c - :export: - -.. kernel-doc:: drivers/base/dma-mapping.c - :export: - -Device Drivers Power Management -------------------------------- - -.. kernel-doc:: drivers/base/power/main.c - :export: - -Device Drivers ACPI Support ---------------------------- - -.. kernel-doc:: drivers/acpi/scan.c - :export: - -.. kernel-doc:: drivers/acpi/scan.c - :internal: - -Device drivers PnP support --------------------------- - -.. kernel-doc:: drivers/pnp/core.c - :internal: - -.. kernel-doc:: drivers/pnp/card.c - :export: - -.. kernel-doc:: drivers/pnp/driver.c - :internal: - -.. kernel-doc:: drivers/pnp/manager.c - :export: - -.. kernel-doc:: drivers/pnp/support.c - :export: - -Userspace IO devices --------------------- - -.. kernel-doc:: drivers/uio/uio.c - :export: - -.. kernel-doc:: include/linux/uio_driver.h - :internal: - -Parallel Port Devices -===================== - -.. kernel-doc:: include/linux/parport.h - :internal: - -.. kernel-doc:: drivers/parport/ieee1284.c - :export: - -.. kernel-doc:: drivers/parport/share.c - :export: - -.. kernel-doc:: drivers/parport/daisy.c - :internal: - -Message-based devices -===================== - -Fusion message devices ----------------------- - -.. kernel-doc:: drivers/message/fusion/mptbase.c - :export: - -.. kernel-doc:: drivers/message/fusion/mptbase.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :export: - -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptctl.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptspi.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptfc.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptlan.c - :internal: - -Sound Devices -============= - -.. kernel-doc:: include/sound/core.h - :internal: - -.. kernel-doc:: sound/sound_core.c - :export: - -.. kernel-doc:: include/sound/pcm.h - :internal: - -.. kernel-doc:: sound/core/pcm.c - :export: - -.. kernel-doc:: sound/core/device.c - :export: - -.. kernel-doc:: sound/core/info.c - :export: - -.. kernel-doc:: sound/core/rawmidi.c - :export: - -.. kernel-doc:: sound/core/sound.c - :export: - -.. kernel-doc:: sound/core/memory.c - :export: - -.. kernel-doc:: sound/core/pcm_memory.c - :export: - -.. kernel-doc:: sound/core/init.c - :export: - -.. kernel-doc:: sound/core/isadma.c - :export: - -.. kernel-doc:: sound/core/control.c - :export: - -.. kernel-doc:: sound/core/pcm_lib.c - :export: - -.. kernel-doc:: sound/core/hwdep.c - :export: - -.. kernel-doc:: sound/core/pcm_native.c - :export: - -.. kernel-doc:: sound/core/memalloc.c - :export: - -16x50 UART Driver -================= - -.. kernel-doc:: drivers/tty/serial/serial_core.c - :export: - -.. kernel-doc:: drivers/tty/serial/8250/8250_core.c - :export: - -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 -------------------- - -.. kernel-doc:: drivers/video/fbdev/core/fbmem.c - :export: - -Frame Buffer Colormap ---------------------- - -.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c - :export: - -Frame Buffer Video Mode Database --------------------------------- - -.. kernel-doc:: drivers/video/fbdev/core/modedb.c - :internal: - -.. kernel-doc:: drivers/video/fbdev/core/modedb.c - :export: - -Frame Buffer Macintosh Video Mode Database ------------------------------------------- - -.. kernel-doc:: drivers/video/fbdev/macmodes.c - :export: - -Frame Buffer Fonts ------------------- - -Refer to the file lib/fonts/fonts.c for more information. - -Input Subsystem -=============== - -Input core ----------- - -.. kernel-doc:: include/linux/input.h - :internal: - -.. kernel-doc:: drivers/input/input.c - :export: - -.. kernel-doc:: drivers/input/ff-core.c - :export: - -.. kernel-doc:: drivers/input/ff-memless.c - :export: - -Multitouch Library ------------------- - -.. kernel-doc:: include/linux/input/mt.h - :internal: - -.. kernel-doc:: drivers/input/input-mt.c - :export: - -Polled input devices --------------------- - -.. kernel-doc:: include/linux/input-polldev.h - :internal: - -.. kernel-doc:: drivers/input/input-polldev.c - :export: - -Matrix keyboards/keypads ------------------------- - -.. kernel-doc:: include/linux/input/matrix_keypad.h - :internal: - -Sparse keymap support ---------------------- - -.. kernel-doc:: include/linux/input/sparse-keymap.h - :internal: - -.. kernel-doc:: drivers/input/sparse-keymap.c - :export: - -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 :c:type:`struct spi_master -`. SPI devices are children of that master, -represented as a :c:type:`struct spi_device ` and -manufactured from :c:type:`struct spi_board_info -` descriptors which are usually provided by -board-specific initialization code. A :c:type:`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 :c:type:`struct spi_message ` objects, -which are processed and completed asynchronously. (There are synchronous -wrappers, however.) Messages are built from one or more -:c:type:`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. - -.. kernel-doc:: include/linux/spi/spi.h - :internal: - -.. kernel-doc:: drivers/spi/spi.c - :functions: spi_register_board_info - -.. kernel-doc:: drivers/spi/spi.c - :export: - -I\ :sup:`2`\ C and SMBus Subsystem -================================== - -I\ :sup:`2`\ C (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 -:c:type:`struct i2c_adapter ` representing each -I2C bus segment it manages. On each I2C bus segment will be I2C devices -represented by a :c:type:`struct i2c_client `. -Those devices will be bound to a :c:type:`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. - -.. kernel-doc:: include/linux/i2c.h - :internal: - -.. kernel-doc:: drivers/i2c/i2c-boardinfo.c - :functions: i2c_register_board_info - -.. kernel-doc:: drivers/i2c/i2c-core.c - :export: - -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. - -.. kernel-doc:: include/linux/hsi/hsi.h - :internal: - -.. kernel-doc:: drivers/hsi/hsi_core.c - :export: - -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 :c:type:`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 :c:type:`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. - -.. kernel-doc:: include/linux/pwm.h - :internal: - -.. kernel-doc:: drivers/pwm/core.c - :export: diff --git a/Documentation/driver-api/frame-buffer.rst b/Documentation/driver-api/frame-buffer.rst new file mode 100644 index 000000000000..9dd3060f027d --- /dev/null +++ b/Documentation/driver-api/frame-buffer.rst @@ -0,0 +1,62 @@ +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 +------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbmem.c + :export: + +Frame Buffer Colormap +--------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c + :export: + +Frame Buffer Video Mode Database +-------------------------------- + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :internal: + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :export: + +Frame Buffer Macintosh Video Mode Database +------------------------------------------ + +.. kernel-doc:: drivers/video/fbdev/macmodes.c + :export: + +Frame Buffer Fonts +------------------ + +Refer to the file lib/fonts/fonts.c for more information. + diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst new file mode 100644 index 000000000000..b50c41011e47 --- /dev/null +++ b/Documentation/driver-api/index.rst @@ -0,0 +1,24 @@ +======================================== +The Linux driver implementer's API guide +======================================== + +The kernel offers a wide variety of interfaces to support the development +of device drivers. This document is an only somewhat organized collection +of some of those interfaces — it will hopefully get better over time! The +available subsections can be seen below. + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + basics + infrastructure + message-based + sound + frame-buffer + input + serial-interfaces + miscellaneous diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst new file mode 100644 index 000000000000..5d50d6733db3 --- /dev/null +++ b/Documentation/driver-api/infrastructure.rst @@ -0,0 +1,169 @@ +Device drivers infrastructure +============================= + +The Basic Device Driver-Model Structures +---------------------------------------- + +.. kernel-doc:: include/linux/device.h + :internal: + +Device Drivers Base +------------------- + +.. kernel-doc:: drivers/base/init.c + :internal: + +.. kernel-doc:: drivers/base/driver.c + :export: + +.. kernel-doc:: drivers/base/core.c + :export: + +.. kernel-doc:: drivers/base/syscore.c + :export: + +.. kernel-doc:: drivers/base/class.c + :export: + +.. kernel-doc:: drivers/base/node.c + :internal: + +.. kernel-doc:: drivers/base/firmware_class.c + :export: + +.. kernel-doc:: drivers/base/transport_class.c + :export: + +.. kernel-doc:: drivers/base/dd.c + :export: + +.. kernel-doc:: include/linux/platform_device.h + :internal: + +.. kernel-doc:: drivers/base/platform.c + :export: + +.. kernel-doc:: drivers/base/bus.c + :export: + +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 +~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :export: + +.. kernel-doc:: include/linux/dma-buf.h + :internal: + +reservation +~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/reservation.c + :doc: Reservation Object Overview + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +fence +~~~~~ + +.. kernel-doc:: drivers/dma-buf/fence.c + :export: + +.. kernel-doc:: include/linux/fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/seqno-fence.c + :export: + +.. kernel-doc:: include/linux/seqno-fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/fence-array.c + :export: + +.. kernel-doc:: include/linux/fence-array.h + :internal: + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +.. kernel-doc:: drivers/dma-buf/sync_file.c + :export: + +.. kernel-doc:: include/linux/sync_file.h + :internal: + +Device Drivers DMA Management +----------------------------- + +.. kernel-doc:: drivers/base/dma-coherent.c + :export: + +.. kernel-doc:: drivers/base/dma-mapping.c + :export: + +Device Drivers Power Management +------------------------------- + +.. kernel-doc:: drivers/base/power/main.c + :export: + +Device Drivers ACPI Support +--------------------------- + +.. kernel-doc:: drivers/acpi/scan.c + :export: + +.. kernel-doc:: drivers/acpi/scan.c + :internal: + +Device drivers PnP support +-------------------------- + +.. kernel-doc:: drivers/pnp/core.c + :internal: + +.. kernel-doc:: drivers/pnp/card.c + :export: + +.. kernel-doc:: drivers/pnp/driver.c + :internal: + +.. kernel-doc:: drivers/pnp/manager.c + :export: + +.. kernel-doc:: drivers/pnp/support.c + :export: + +Userspace IO devices +-------------------- + +.. kernel-doc:: drivers/uio/uio.c + :export: + +.. kernel-doc:: include/linux/uio_driver.h + :internal: + diff --git a/Documentation/driver-api/input.rst b/Documentation/driver-api/input.rst new file mode 100644 index 000000000000..d05bf58fa83e --- /dev/null +++ b/Documentation/driver-api/input.rst @@ -0,0 +1,51 @@ +Input Subsystem +=============== + +Input core +---------- + +.. kernel-doc:: include/linux/input.h + :internal: + +.. kernel-doc:: drivers/input/input.c + :export: + +.. kernel-doc:: drivers/input/ff-core.c + :export: + +.. kernel-doc:: drivers/input/ff-memless.c + :export: + +Multitouch Library +------------------ + +.. kernel-doc:: include/linux/input/mt.h + :internal: + +.. kernel-doc:: drivers/input/input-mt.c + :export: + +Polled input devices +-------------------- + +.. kernel-doc:: include/linux/input-polldev.h + :internal: + +.. kernel-doc:: drivers/input/input-polldev.c + :export: + +Matrix keyboards/keypads +------------------------ + +.. kernel-doc:: include/linux/input/matrix_keypad.h + :internal: + +Sparse keymap support +--------------------- + +.. kernel-doc:: include/linux/input/sparse-keymap.h + :internal: + +.. kernel-doc:: drivers/input/sparse-keymap.c + :export: + diff --git a/Documentation/driver-api/message-based.rst b/Documentation/driver-api/message-based.rst new file mode 100644 index 000000000000..ef5867a7de20 --- /dev/null +++ b/Documentation/driver-api/message-based.rst @@ -0,0 +1,30 @@ +Message-based devices +===================== + +Fusion message devices +---------------------- + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptctl.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptspi.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptfc.c + :internal: + +.. kernel-doc:: drivers/message/fusion/mptlan.c + :internal: + diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst new file mode 100644 index 000000000000..8da7d115bafc --- /dev/null +++ b/Documentation/driver-api/miscellaneous.rst @@ -0,0 +1,50 @@ +Parallel Port Devices +===================== + +.. kernel-doc:: include/linux/parport.h + :internal: + +.. kernel-doc:: drivers/parport/ieee1284.c + :export: + +.. kernel-doc:: drivers/parport/share.c + :export: + +.. kernel-doc:: drivers/parport/daisy.c + :internal: + +16x50 UART Driver +================= + +.. kernel-doc:: drivers/tty/serial/serial_core.c + :export: + +.. kernel-doc:: drivers/tty/serial/8250/8250_core.c + :export: + +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 :c:type:`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 :c:type:`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. + +.. kernel-doc:: include/linux/pwm.h + :internal: + +.. kernel-doc:: drivers/pwm/core.c + :export: + diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst new file mode 100644 index 000000000000..d0d65e58c14b --- /dev/null +++ b/Documentation/driver-api/serial-interfaces.rst @@ -0,0 +1,115 @@ +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 :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`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 :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`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. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: + +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (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 +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`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. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: + +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. + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst new file mode 100644 index 000000000000..afef6eabc073 --- /dev/null +++ b/Documentation/driver-api/sound.rst @@ -0,0 +1,54 @@ +Sound Devices +============= + +.. kernel-doc:: include/sound/core.h + :internal: + +.. kernel-doc:: sound/sound_core.c + :export: + +.. kernel-doc:: include/sound/pcm.h + :internal: + +.. kernel-doc:: sound/core/pcm.c + :export: + +.. kernel-doc:: sound/core/device.c + :export: + +.. kernel-doc:: sound/core/info.c + :export: + +.. kernel-doc:: sound/core/rawmidi.c + :export: + +.. kernel-doc:: sound/core/sound.c + :export: + +.. kernel-doc:: sound/core/memory.c + :export: + +.. kernel-doc:: sound/core/pcm_memory.c + :export: + +.. kernel-doc:: sound/core/init.c + :export: + +.. kernel-doc:: sound/core/isadma.c + :export: + +.. kernel-doc:: sound/core/control.c + :export: + +.. kernel-doc:: sound/core/pcm_lib.c + :export: + +.. kernel-doc:: sound/core/hwdep.c + :export: + +.. kernel-doc:: sound/core/pcm_native.c + :export: + +.. kernel-doc:: sound/core/memalloc.c + :export: + diff --git a/Documentation/index.rst b/Documentation/index.rst index 0d6992b897c8..9fe5e0cacdd0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,7 +13,7 @@ Contents: kernel-documentation dev-tools/tools - driver-api/drivers + driver-api/index media/index gpu/index -- cgit v1.2.3 From 70fc1f547a91c137913a23a0f7a4a89c33930c6a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sat, 20 Aug 2016 13:24:56 -0600 Subject: docs: Pull the HSI documentation together The HSI subsystem documentation was split across hsi.txt and the device-drivers docbook. Now that the latter has been converted to Sphinx, pull in the HSI document so that it's all in one place. Acked-by: Sebastian Reichel Signed-off-by: Jonathan Corbet --- Documentation/driver-api/serial-interfaces.rst | 82 ++++++++++++++++++++++++-- Documentation/hsi.txt | 75 ----------------------- MAINTAINERS | 2 +- 3 files changed, 79 insertions(+), 80 deletions(-) delete mode 100644 Documentation/hsi.txt (limited to 'Documentation') diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst index d0d65e58c14b..07c58971a322 100644 --- a/Documentation/driver-api/serial-interfaces.rst +++ b/Documentation/driver-api/serial-interfaces.rst @@ -102,10 +102,84 @@ i2c_adapter devices which don't support those I2C operations. 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. +1. Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +2. HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +3. hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ .. kernel-doc:: include/linux/hsi/hsi.h :internal: diff --git a/Documentation/hsi.txt b/Documentation/hsi.txt deleted file mode 100644 index 6ac6cd51852a..000000000000 --- a/Documentation/hsi.txt +++ /dev/null @@ -1,75 +0,0 @@ -HSI - High-speed Synchronous Serial Interface - -1. Introduction -~~~~~~~~~~~~~~~ - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -+------------+ +---------------+ -| Cellular | | Application | -| Die | | Die | -| | - - - - - - CAWAKE - - - - - - >| | -| T|------------ CADATA ------------>|R | -| X|------------ CAFLAG ------------>|X | -| |<----------- ACREADY ------------| | -| | | | -| | | | -| |< - - - - - ACWAKE - - - - - - -| | -| R|<----------- ACDATA -------------|T | -| X|<----------- ACFLAG -------------|X | -| |------------ CAREADY ----------->| | -| | | | -| | | | -+------------+ +---------------+ - -2. HSI Subsystem in Linux -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device -~~~~~~~~~~~~~~~~~~ - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -* HSC_RESET: - - flush the HSI port - -* HSC_SET_PM - - enable or disable the client. - -* HSC_SEND_BREAK - - send break - -* HSC_SET_RX - - set RX configuration - -* HSC_GET_RX - - get RX configuration - -* HSC_SET_TX - - set TX configuration - -* HSC_GET_TX - - get TX configuration diff --git a/MAINTAINERS b/MAINTAINERS index 810723537aa5..769a2fd4af72 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5606,7 +5606,7 @@ M: Sebastian Reichel T: git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi.git S: Maintained F: Documentation/ABI/testing/sysfs-bus-hsi -F: Documentation/hsi.txt +F: Documentation/device-drivers/serial-interfaces.rst F: drivers/hsi/ F: include/linux/hsi/ F: include/uapi/linux/hsi/ -- cgit v1.2.3 From 5e995786850e78b7950f6979a6bdd3990abc89cd Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 6 Sep 2016 07:15:24 -0600 Subject: docs: split up serial-interfaces.rst It never made sense to keep these documents together; move each into its own file. Drop the section numbering on hsi.txt on its way to its own file. Suggested-by: Sebastian Reichel Signed-off-by: Jonathan Corbet --- Documentation/driver-api/hsi.rst | 88 ++++++++++++ Documentation/driver-api/i2c.rst | 46 ++++++ Documentation/driver-api/index.rst | 4 +- Documentation/driver-api/serial-interfaces.rst | 189 ------------------------- Documentation/driver-api/spi.rst | 53 +++++++ 5 files changed, 190 insertions(+), 190 deletions(-) create mode 100644 Documentation/driver-api/hsi.rst create mode 100644 Documentation/driver-api/i2c.rst delete mode 100644 Documentation/driver-api/serial-interfaces.rst create mode 100644 Documentation/driver-api/spi.rst (limited to 'Documentation') diff --git a/Documentation/driver-api/hsi.rst b/Documentation/driver-api/hsi.rst new file mode 100644 index 000000000000..f9cec02b72a1 --- /dev/null +++ b/Documentation/driver-api/hsi.rst @@ -0,0 +1,88 @@ +High Speed Synchronous Serial Interface (HSI) +============================================= + +Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + diff --git a/Documentation/driver-api/i2c.rst b/Documentation/driver-api/i2c.rst new file mode 100644 index 000000000000..f3939f7852bd --- /dev/null +++ b/Documentation/driver-api/i2c.rst @@ -0,0 +1,46 @@ +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ C (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 +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`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. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b50c41011e47..8e259c5d0322 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -20,5 +20,7 @@ available subsections can be seen below. sound frame-buffer input - serial-interfaces + spi + i2c + hsi miscellaneous diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst deleted file mode 100644 index 07c58971a322..000000000000 --- a/Documentation/driver-api/serial-interfaces.rst +++ /dev/null @@ -1,189 +0,0 @@ -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 :c:type:`struct spi_master -`. SPI devices are children of that master, -represented as a :c:type:`struct spi_device ` and -manufactured from :c:type:`struct spi_board_info -` descriptors which are usually provided by -board-specific initialization code. A :c:type:`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 :c:type:`struct spi_message ` objects, -which are processed and completed asynchronously. (There are synchronous -wrappers, however.) Messages are built from one or more -:c:type:`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. - -.. kernel-doc:: include/linux/spi/spi.h - :internal: - -.. kernel-doc:: drivers/spi/spi.c - :functions: spi_register_board_info - -.. kernel-doc:: drivers/spi/spi.c - :export: - -I\ :sup:`2`\ C and SMBus Subsystem -================================== - -I\ :sup:`2`\ C (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 -:c:type:`struct i2c_adapter ` representing each -I2C bus segment it manages. On each I2C bus segment will be I2C devices -represented by a :c:type:`struct i2c_client `. -Those devices will be bound to a :c:type:`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. - -.. kernel-doc:: include/linux/i2c.h - :internal: - -.. kernel-doc:: drivers/i2c/i2c-boardinfo.c - :functions: i2c_register_board_info - -.. kernel-doc:: drivers/i2c/i2c-core.c - :export: - -High Speed Synchronous Serial Interface (HSI) -============================================= - -1. Introduction ---------------- - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -:: - - +------------+ +---------------+ - | Cellular | | Application | - | Die | | Die | - | | - - - - - - CAWAKE - - - - - - >| | - | T|------------ CADATA ------------>|R | - | X|------------ CAFLAG ------------>|X | - | |<----------- ACREADY ------------| | - | | | | - | | | | - | |< - - - - - ACWAKE - - - - - - -| | - | R|<----------- ACDATA -------------|T | - | X|<----------- ACFLAG -------------|X | - | |------------ CAREADY ----------->| | - | | | | - | | | | - +------------+ +---------------+ - -2. HSI Subsystem in Linux -------------------------- - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device ------------------- - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -HSC_RESET - flush the HSI port - -HSC_SET_PM - enable or disable the client. - -HSC_SEND_BREAK - send break - -HSC_SET_RX - set RX configuration - -HSC_GET_RX - get RX configuration - -HSC_SET_TX - set TX configuration - -HSC_GET_TX - get TX configuration - -The kernel HSI API ------------------- - -.. kernel-doc:: include/linux/hsi/hsi.h - :internal: - -.. kernel-doc:: drivers/hsi/hsi_core.c - :export: - diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst new file mode 100644 index 000000000000..f64cb666498a --- /dev/null +++ b/Documentation/driver-api/spi.rst @@ -0,0 +1,53 @@ +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 :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`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 :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`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. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: -- cgit v1.2.3 From d36bbab661d9da8dec97acd2d9647e86c70187e8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 6 Sep 2016 07:22:03 -0600 Subject: docs: Don't format internal MPT docs This is the driver API document, so the internal stuff is just noise here. Signed-off-by: Jonathan Corbet --- Documentation/driver-api/message-based.rst | 18 ------------------ 1 file changed, 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/message-based.rst b/Documentation/driver-api/message-based.rst index ef5867a7de20..18ff94ef6d8e 100644 --- a/Documentation/driver-api/message-based.rst +++ b/Documentation/driver-api/message-based.rst @@ -7,24 +7,6 @@ Fusion message devices .. kernel-doc:: drivers/message/fusion/mptbase.c :export: -.. kernel-doc:: drivers/message/fusion/mptbase.c - :internal: - .. kernel-doc:: drivers/message/fusion/mptscsih.c :export: -.. kernel-doc:: drivers/message/fusion/mptscsih.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptctl.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptspi.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptfc.c - :internal: - -.. kernel-doc:: drivers/message/fusion/mptlan.c - :internal: - -- cgit v1.2.3 From 3d8819b761e5bfb25a83b9c843694c19d0a82c94 Mon Sep 17 00:00:00 2001 From: Robert Foss Date: Thu, 8 Sep 2016 18:44:23 -0400 Subject: Documentation/filesystems: Fixed typo Fixed a -> an typo. Signed-off-by: Robert Foss Acked-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/filesystems/proc.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 68080ad6a75e..fcc1ac094282 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc symbol the task is blocked in - or "0" if not blocked. pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE - smaps a extension based on maps, showing the memory consumption of + smaps an extension based on maps, showing the memory consumption of each mapping and flags associated with it numa_maps an extension based on maps, showing the memory locality and binding policy as well as mem usage (in pages) of each mapping. -- cgit v1.2.3 From b495360e30621e22f7a69a239de0d68bc4e383dd Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 7 Sep 2016 09:12:56 +0200 Subject: doc-rst:c-domain: fix sphinx version incompatibility The self.indexnode's tuple has changed in sphinx version 1.4, from a former 4 element tuple to a 5 element tuple. https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/sphinx/cdomain.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 9eb714ada394..5f0c7ed0ddc7 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -29,11 +29,15 @@ u""" from docutils.parsers.rst import directives +import sphinx from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain __version__ = '1.0' +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + def setup(app): app.override_domain(CDomain) @@ -85,8 +89,14 @@ class CObject(Base_CObject): indextext = self.get_index_text(name) if indextext: - self.indexnode['entries'].append(('single', indextext, - targetname, '', None)) + if major == 1 and minor < 4: + # indexnode's tuple changed in 1.4 + # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c + self.indexnode['entries'].append( + ('single', indextext, targetname, '')) + else: + self.indexnode['entries'].append( + ('single', indextext, targetname, '', None)) class CDomain(Base_CDomain): -- cgit v1.2.3 From 56cd869288f06cb59b81d3f75568e0d7dc89091f Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 7 Sep 2016 09:12:57 +0200 Subject: doc-rst:c-domain: function-like macros arguments Handle signatures of function-like macros well. Don't try to deduce arguments types of function-like macros. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 5f0c7ed0ddc7..df0419c62096 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -1,4 +1,5 @@ # -*- coding: utf-8; mode: python -*- +# pylint: disable=W0141,C0113,C0103,C0325 u""" cdomain ~~~~~~~ @@ -25,11 +26,18 @@ u""" * :c:func:`VIDIOC_LOG_STATUS` or * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) + + * Handle signatures of function-like macros well. Don't try to deduce + arguments types of function-like macros. + """ +from docutils import nodes from docutils.parsers.rst import directives import sphinx +from sphinx import addnodes +from sphinx.domains.c import c_funcptr_sig_re, c_sig_re from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain @@ -57,9 +65,54 @@ class CObject(Base_CObject): "name" : directives.unchanged } + def handle_func_like_macro(self, sig, signode): + u"""Handles signatures of function-like macros. + + If the objtype is 'function' and the the signature ``sig`` is a + function-like macro, the name of the macro is returned. Otherwise + ``False`` is returned. """ + + if not self.objtype == 'function': + return False + + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + + rettype, fullname, arglist, _const = m.groups() + arglist = arglist.strip() + if rettype or not arglist: + return False + + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + arglist = [a.strip() for a in arglist.split(",")] + + # has the first argument a type? + if len(arglist[0].split(" ")) > 1: + return False + + # This is a function-like macro, it's arguments are typeless! + signode += addnodes.desc_name(fullname, fullname) + paramlist = addnodes.desc_parameterlist() + signode += paramlist + + for argname in arglist: + param = addnodes.desc_parameter('', '', noemph=True) + # separate by non-breaking space in the output + param += nodes.emphasis(argname, argname) + paramlist += param + + return fullname + def handle_signature(self, sig, signode): """Transform a C signature into RST nodes.""" - fullname = super(CObject, self).handle_signature(sig, signode) + + fullname = self.handle_func_like_macro(sig, signode) + if not fullname: + fullname = super(CObject, self).handle_signature(sig, signode) + if "name" in self.options: if self.objtype == 'function': fullname = self.options["name"] -- cgit v1.2.3 From e92ae527e7ba59f9175221a4f5422fb5eaec3dc4 Mon Sep 17 00:00:00 2001 From: Christoph Hellwig Date: Sun, 11 Sep 2016 15:58:53 +0200 Subject: DMA-API-HOWTO: is no more So don't mention it. Signed-off-by: Christoph Hellwig Signed-off-by: Jonathan Corbet --- Documentation/DMA-API-HOWTO.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 781024ef9050..494ffac655ee 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -931,10 +931,8 @@ to "Closing". 1) Struct scatterlist requirements. - Don't invent the architecture specific struct scatterlist; just use - . You need to enable - CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs - (including software IOMMU). + You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture + supports IOMMUs (including software IOMMU). 2) ARCH_DMA_MINALIGN -- cgit v1.2.3 From 829f4c362fc988381870b82cd7405f76fc077855 Mon Sep 17 00:00:00 2001 From: Laurent Navet Date: Thu, 15 Sep 2016 22:49:53 +0200 Subject: docs/driver-model: fix typo No need to be be, just be should be sufficient. Signed-off-by: Laurent Navet Signed-off-by: Jonathan Corbet --- Documentation/driver-model/device.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt index 1e70220d20f4..2403eb856187 100644 --- a/Documentation/driver-model/device.txt +++ b/Documentation/driver-model/device.txt @@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs. Please see Documentation/filesystems/sysfs.txt for more information on how sysfs works. -As explained in Documentation/kobject.txt, device attributes must be be +As explained in Documentation/kobject.txt, device attributes must be created before the KOBJ_ADD uevent is generated. The only way to realize that is by defining an attribute group. -- cgit v1.2.3