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
- <asm-generic/scatterlist.h>. 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
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index a558dfcc9e2d..736f5916daea 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 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LinuxDriversAPI">
- <bookinfo>
- <title>Linux Device Drivers</title>
-
- <legalnotice>
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="Basics">
- <title>Driver Basics</title>
- <sect1><title>Driver Entry and Exit points</title>
-!Iinclude/linux/init.h
- </sect1>
-
- <sect1><title>Atomic and pointer manipulation</title>
-!Iarch/x86/include/asm/atomic.h
- </sect1>
-
- <sect1><title>Delaying, scheduling, and timer routines</title>
-!Iinclude/linux/sched.h
-!Ekernel/sched/core.c
-!Ikernel/sched/cpupri.c
-!Ikernel/sched/fair.c
-!Iinclude/linux/completion.h
-!Ekernel/time/timer.c
- </sect1>
- <sect1><title>Wait queues and Wake events</title>
-!Iinclude/linux/wait.h
-!Ekernel/sched/wait.c
- </sect1>
- <sect1><title>High-resolution timers</title>
-!Iinclude/linux/ktime.h
-!Iinclude/linux/hrtimer.h
-!Ekernel/time/hrtimer.c
- </sect1>
- <sect1><title>Workqueues and Kevents</title>
-!Iinclude/linux/workqueue.h
-!Ekernel/workqueue.c
- </sect1>
- <sect1><title>Internal Functions</title>
-!Ikernel/exit.c
-!Ikernel/signal.c
-!Iinclude/linux/kthread.h
-!Ekernel/kthread.c
- </sect1>
-
- <sect1><title>Kernel objects manipulation</title>
-<!--
-X!Iinclude/linux/kobject.h
--->
-!Elib/kobject.c
- </sect1>
-
- <sect1><title>Kernel utility functions</title>
-!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
- </sect1>
-
- <sect1><title>Device Resource Management</title>
-!Edrivers/base/devres.c
- </sect1>
-
- </chapter>
-
- <chapter id="devdrivers">
- <title>Device drivers infrastructure</title>
- <sect1><title>The Basic Device Driver-Model Structures </title>
-!Iinclude/linux/device.h
- </sect1>
- <sect1><title>Device Drivers Base</title>
-!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
-<!-- Cannot be included, because
- attribute_container_add_class_device_adapter
- and attribute_container_classdev_to_container
- exceed allowed 44 characters maximum
-X!Edrivers/base/attribute_container.c
--->
-!Edrivers/base/dd.c
-<!--
-X!Edrivers/base/interface.c
--->
-!Iinclude/linux/platform_device.h
-!Edrivers/base/platform.c
-!Edrivers/base/bus.c
- </sect1>
- <sect1>
- <title>Buffer Sharing and Synchronization</title>
- <para>
- 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.
- </para>
- <para>
- This is used, for example, by drm "prime" multi-GPU support, but
- is of course not limited to GPU use cases.
- </para>
- <para>
- 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.
- </para>
- <sect2><title>dma-buf</title>
-!Edrivers/dma-buf/dma-buf.c
-!Iinclude/linux/dma-buf.h
- </sect2>
- <sect2><title>reservation</title>
-!Pdrivers/dma-buf/reservation.c Reservation Object Overview
-!Edrivers/dma-buf/reservation.c
-!Iinclude/linux/reservation.h
- </sect2>
- <sect2><title>fence</title>
-!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
- </sect2>
- </sect1>
- <sect1><title>Device Drivers DMA Management</title>
-!Edrivers/base/dma-coherent.c
-!Edrivers/base/dma-mapping.c
- </sect1>
- <sect1><title>Device Drivers Power Management</title>
-!Edrivers/base/power/main.c
- </sect1>
- <sect1><title>Device Drivers ACPI Support</title>
-<!-- Internal functions only
-X!Edrivers/acpi/sleep/main.c
-X!Edrivers/acpi/sleep/wakeup.c
-X!Edrivers/acpi/motherboard.c
-X!Edrivers/acpi/bus.c
--->
-!Edrivers/acpi/scan.c
-!Idrivers/acpi/scan.c
-<!-- No correct structured comments
-X!Edrivers/acpi/pci_bind.c
--->
- </sect1>
- <sect1><title>Device drivers PnP support</title>
-!Idrivers/pnp/core.c
-<!-- No correct structured comments
-X!Edrivers/pnp/system.c
- -->
-!Edrivers/pnp/card.c
-!Idrivers/pnp/driver.c
-!Edrivers/pnp/manager.c
-!Edrivers/pnp/support.c
- </sect1>
- <sect1><title>Userspace IO devices</title>
-!Edrivers/uio/uio.c
-!Iinclude/linux/uio_driver.h
- </sect1>
- </chapter>
-
- <chapter id="parportdev">
- <title>Parallel Port Devices</title>
-!Iinclude/linux/parport.h
-!Edrivers/parport/ieee1284.c
-!Edrivers/parport/share.c
-!Idrivers/parport/daisy.c
- </chapter>
-
- <chapter id="message_devices">
- <title>Message-based devices</title>
- <sect1><title>Fusion message devices</title>
-!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
- </sect1>
- </chapter>
-
- <chapter id="snddev">
- <title>Sound Devices</title>
-!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
-<!-- FIXME: Removed for now since no structured comments in source
-X!Isound/sound_firmware.c
--->
- </chapter>
-
-
- <chapter id="uart16x50">
- <title>16x50 UART Driver</title>
-!Edrivers/tty/serial/serial_core.c
-!Edrivers/tty/serial/8250/8250_core.c
- </chapter>
-
- <chapter id="fbdev">
- <title>Frame Buffer Library</title>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <sect1><title>Frame Buffer Memory</title>
-!Edrivers/video/fbdev/core/fbmem.c
- </sect1>
-<!--
- <sect1><title>Frame Buffer Console</title>
-X!Edrivers/video/console/fbcon.c
- </sect1>
--->
- <sect1><title>Frame Buffer Colormap</title>
-!Edrivers/video/fbdev/core/fbcmap.c
- </sect1>
-<!-- FIXME:
- drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
- out until somebody adds docs. KAO
- <sect1><title>Frame Buffer Generic Functions</title>
-X!Idrivers/video/fbgen.c
- </sect1>
-KAO -->
- <sect1><title>Frame Buffer Video Mode Database</title>
-!Idrivers/video/fbdev/core/modedb.c
-!Edrivers/video/fbdev/core/modedb.c
- </sect1>
- <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
-!Edrivers/video/fbdev/macmodes.c
- </sect1>
- <sect1><title>Frame Buffer Fonts</title>
- <para>
- Refer to the file lib/fonts/fonts.c for more information.
- </para>
-<!-- FIXME: Removed for now since no structured comments in source
-X!Ilib/fonts/fonts.c
--->
- </sect1>
- </chapter>
-
- <chapter id="input_subsystem">
- <title>Input Subsystem</title>
- <sect1><title>Input core</title>
-!Iinclude/linux/input.h
-!Edrivers/input/input.c
-!Edrivers/input/ff-core.c
-!Edrivers/input/ff-memless.c
- </sect1>
- <sect1><title>Multitouch Library</title>
-!Iinclude/linux/input/mt.h
-!Edrivers/input/input-mt.c
- </sect1>
- <sect1><title>Polled input devices</title>
-!Iinclude/linux/input-polldev.h
-!Edrivers/input/input-polldev.c
- </sect1>
- <sect1><title>Matrix keyboards/keypads</title>
-!Iinclude/linux/input/matrix_keypad.h
- </sect1>
- <sect1><title>Sparse keymap support</title>
-!Iinclude/linux/input/sparse-keymap.h
-!Edrivers/input/sparse-keymap.c
- </sect1>
- </chapter>
-
- <chapter id="spi">
- <title>Serial Peripheral Interface (SPI)</title>
- <para>
- 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.
- </para>
- <para>
- 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.)
- </para>
- <para>
- 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
- <structname>struct spi_master</structname>.
- SPI devices are children of that master, represented as a
- <structname>struct spi_device</structname> and manufactured from
- <structname>struct spi_board_info</structname> descriptors which
- are usually provided by board-specific initialization code.
- A <structname>struct spi_driver</structname> is called a
- "Protocol Driver", and is bound to a spi_device using normal
- driver model calls.
- </para>
- <para>
- The I/O model is a set of queued messages. Protocol drivers
- submit one or more <structname>struct spi_message</structname>
- objects, which are processed and completed asynchronously.
- (There are synchronous wrappers, however.) Messages are
- built from one or more <structname>struct spi_transfer</structname>
- 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.
- </para>
-!Iinclude/linux/spi/spi.h
-!Fdrivers/spi/spi.c spi_register_board_info
-!Edrivers/spi/spi.c
- </chapter>
-
- <chapter id="i2c">
- <title>I<superscript>2</superscript>C and SMBus Subsystem</title>
-
- <para>
- I<superscript>2</superscript>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.
- </para>
-
- <para>
- 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 <structname>struct i2c_adapter</structname> representing
- each I2C bus segment it manages.
- On each I2C bus segment will be I2C devices represented by a
- <structname>struct i2c_client</structname>. Those devices will
- be bound to a <structname>struct i2c_driver</structname>,
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
-!Iinclude/linux/i2c.h
-!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
-!Edrivers/i2c/i2c-core.c
- </chapter>
-
- <chapter id="hsi">
- <title>High Speed Synchronous Serial Interface (HSI)</title>
-
- <para>
- 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.
- </para>
-
-!Iinclude/linux/hsi/hsi.h
-!Edrivers/hsi/hsi_core.c
- </chapter>
-
- <chapter id="pwm">
- <title>Pulse-Width Modulation (PWM)</title>
- <para>
- Pulse-width modulation is a modulation technique primarily used to
- control power supplied to electrical devices.
- </para>
- <para>
- 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 <structname>struct pwm_chip</structname>. Providers are
- expected to embed this structure in a driver-specific structure. This
- structure contains fields that describe a particular chip.
- </para>
- <para>
- A chip exposes one or more PWM signal sources, each of which exposed
- as a <structname>struct pwm_device</structname>. Operations can be
- performed on PWM devices to control the period, duty cycle, polarity
- and active state of the signal.
- </para>
- <para>
- Note that PWM devices are exclusive resources: they can always only be
- used by one consumer at a time.
- </para>
-!Iinclude/linux/pwm.h
-!Edrivers/pwm/core.c
- </chapter>
-
-</book>
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/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/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 <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 <i2c_client>`.
+Those devices will be bound to a :c:type:`struct i2c_driver
+<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
new file mode 100644
index 000000000000..8e259c5d0322
--- /dev/null
+++ b/Documentation/driver-api/index.rst
@@ -0,0 +1,26 @@
+========================================
+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
+ spi
+ i2c
+ hsi
+ 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..18ff94ef6d8e
--- /dev/null
+++ b/Documentation/driver-api/message-based.rst
@@ -0,0 +1,12 @@
+Message-based devices
+=====================
+
+Fusion message devices
+----------------------
+
+.. kernel-doc:: drivers/message/fusion/mptbase.c
+ :export:
+
+.. kernel-doc:: drivers/message/fusion/mptscsih.c
+ :export:
+
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 <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 <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/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/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_master>`. SPI devices are children of that master,
+represented as a :c:type:`struct spi_device <spi_device>` and
+manufactured from :c:type:`struct spi_board_info
+<spi_board_info>` descriptors which are usually provided by
+board-specific initialization code. A :c:type:`struct spi_driver
+<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 <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 <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:
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.
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.
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/Documentation/index.rst b/Documentation/index.rst
index 05eded59820e..9fe5e0cacdd0 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -13,6 +13,7 @@ Contents:
kernel-documentation
dev-tools/tools
+ driver-api/index
media/index
gpu/index
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 9eb714ada394..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,15 +26,26 @@ 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
__version__ = '1.0'
+# Get Sphinx version
+major, minor, patch = map(int, sphinx.__version__.split("."))
+
def setup(app):
app.override_domain(CDomain)
@@ -53,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"]
@@ -85,8 +142,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):
diff --git a/MAINTAINERS b/MAINTAINERS
index 810723537aa5..769a2fd4af72 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5606,7 +5606,7 @@ M: Sebastian Reichel <sre@kernel.org>
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/