Get rid of Docbook

13/53

---
 Documentation/conf.py        |  2 ++
 Documentation/crypto/conf.py | 10 ++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 Documentation/crypto/conf.py
index 15f34d6863a7..ce62723491d4 100644
@@ -351,6 +351,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('core-api/index', 'core-api.tex', 'The kernel core API manual',
      'The kernel development community', 'manual'),
+    ('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
+     'The kernel development community', 'manual'),
     ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
      'The kernel development community', 'manual'),
     ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',

new file mode 100644
index 000000000000..4335d251ddf3
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Crypto API'
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
+     'The kernel development community', 'manual'),
+]

2.9.3


______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/
---
 fs/jbd2/transaction.c | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)
index 9ee4832b6f8b..fe7f4a373436 100644
@@ -409,25 +409,6 @@ static handle_t *new_handle(int nblocks)
 	return handle;
 }
 
-/**
- * handle_t *jbd2_journal_start() - Obtain a new handle.
- * @journal: Journal to start transaction on.
- * @nblocks: number of block buffer we might modify
- *
- * We make sure that the transaction can guarantee at least nblocks of
- * modified buffers in the log.  We block until the log can guarantee
- * that much space. Additionally, if rsv_blocks > 0, we also create another
- * handle with rsv_blocks reserved blocks in the journal. This handle is
- * is stored in h_rsv_handle. It is not attached to any particular transaction
- * and thus doesn't block transaction commit. If the caller uses this reserved
- * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
- * on the parent handle will dispose the reserved one. Reserved handle has to
- * be converted to a normal handle using jbd2_journal_start_reserved() before
- * it can be used.
- *
- * Return a pointer to a newly allocated handle, or an ERR_PTR() value
- * on failure.
- */
 handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
 			      gfp_t gfp_mask, unsigned int type,
 			      unsigned int line_no)

@@ -478,6 +459,25 @@ handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
 EXPORT_SYMBOL(jbd2__journal_start);
 
 
+/**
+ * handle_t *jbd2_journal_start() - Obtain a new handle.
+ * @journal: Journal to start transaction on.
+ * @nblocks: number of block buffer we might modify
+ *
+ * We make sure that the transaction can guarantee at least nblocks of
+ * modified buffers in the log.  We block until the log can guarantee
+ * that much space. Additionally, if rsv_blocks > 0, we also create another
+ * handle with rsv_blocks reserved blocks in the journal. This handle is
+ * is stored in h_rsv_handle. It is not attached to any particular transaction
+ * and thus doesn't block transaction commit. If the caller uses this reserved
+ * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
+ * on the parent handle will dispose the reserved one. Reserved handle has to
+ * be converted to a normal handle using jbd2_journal_start_reserved() before
+ * it can be used.
+ *
+ * Return a pointer to a newly allocated handle, or an ERR_PTR() value
+ * on failure.
+ */
 handle_t *jbd2_journal_start(journal_t *journal, int nblocks)
 {
 	return jbd2__journal_start(journal, nblocks, 0, GFP_NOFS, 0, 0);

2.9.3
---
 fs/jbd2/transaction.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
index fe7f4a373436..38e1dcabbaca 100644
@@ -1066,10 +1066,10 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
  * @handle: transaction to add buffer modifications to
  * @bh:     bh to be used for metadata writes
  *
- * Returns an error code or 0 on success.
+ * Returns: error code or 0 on success.
  *
  * In full data journalling mode the buffer may be of type BJ_AsyncData,
- * because we're write()ing a buffer which is also part of a shared mapping.
+ * because we're ``write()ing`` a buffer which is also part of a shared mapping.
  */
 
 int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)

2.9.3
---
 drivers/ata/libata-scsi.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
index 49ba9834c715..dcd38d9e9804 100644
@@ -3398,9 +3398,10 @@ static size_t ata_format_dsm_trim_descr(struct scsi_cmnd *cmd, u32 trmax,
  *
  * Translate a SCSI WRITE SAME command to be either a DSM TRIM command or
  * an SCT Write Same command.
- * Based on WRITE SAME has the UNMAP flag
- *   When set translate to DSM TRIM
- *   When clear translate to SCT Write Same
+ * Based on WRITE SAME has the UNMAP flag:
+ *
+ *   - When set translate to DSM TRIM
+ *   - When clear translate to SCT Write Same
  */
 static unsigned int ata_scsi_write_same_xlat(struct ata_queued_cmd *qc)
 {

2.9.3
---
 Documentation/DocBook/Makefile            |   2 +-
 Documentation/DocBook/s390-drivers.tmpl   | 161 ------------------------------
 Documentation/driver-api/index.rst        |   1 +
 Documentation/driver-api/s390-drivers.rst | 111 ++++++++++++++++++++
 4 files changed, 113 insertions(+), 162 deletions(-)
 delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
 create mode 100644 Documentation/driver-api/s390-drivers.rst
index abe71345160b..a25bf10384e1 100644
@@ -10,7 +10,7 @@ DOCBOOKS := z8530book.xml  \
 	    networking.xml \
 	    lsm.xml \
 	    mtdnand.xml librs.xml rapidio.xml \
-	    s390-drivers.xml scsi.xml \
+	    scsi.xml \
 	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)

index c3c50b1bb96c..a9687731810e 100644
@@ -34,6 +34,7 @@ available subsections can be seen below.
    edac
    libata
    miscellaneous
+   s390-drivers
    vme
    80211/index
    uio-howto

2.9.3
---
 drivers/net/phy/phy.c     | 1 +
 include/linux/netdevice.h | 9 +++++----
 include/net/sock.h        | 9 ++++-----
 net/core/datagram.c       | 2 +-
 net/core/sock.c           | 7 +++++--
 5 files changed, 16 insertions(+), 12 deletions(-)
index 82ab8fb82587..709b8be53443 100644
@@ -377,6 +377,7 @@ static void phy_sanitize_settings(struct phy_device *phydev)
  * @cmd: ethtool_cmd
  *
  * A few notes about parameter checking:
+ *
  * - We don't set port or transceiver, so we don't care what they
  *   were set to.
  * - phy_start_aneg() will make sure forced settings are sane, and

index 9c23bd2efb56..56d54b6fac45 100644
@@ -1433,13 +1433,14 @@ enum netdev_priv_flags {
 
 /**
  *	struct net_device - The DEVICE structure.
- *		Actually, this whole structure is a big mistake.  It mixes I/O
- *		data with strictly "high-level" data, and it has to know about
- *		almost every data structure used in the INET module.
+ *
+ *	Actually, this whole structure is a big mistake.  It mixes I/O
+ *	data with strictly "high-level" data, and it has to know about
+ *	almost every data structure used in the INET module.
  *
  *	@name:	This is the first field of the "visible" part of this structure
  *		(i.e. as seen by users in the "Space.c" file).  It is the name
- *	 	of the interface.
+ *		of the interface.
  *
  *	@name_hlist: 	Device name hash chain, please keep it close to name[]
  *	@ifalias:	SNMP alias

index 66349e49d468..9ca99b5c1328 100644
@@ -1953,11 +1953,10 @@ static inline bool sk_has_allocations(const struct sock *sk)
  * The purpose of the skwq_has_sleeper and sock_poll_wait is to wrap the memory
  * barrier call. They were added due to the race found within the tcp code.
  *
- * Consider following tcp code paths:
+ * Consider following tcp code paths::
  *
- * CPU1                  CPU2
- *
- * sys_select            receive packet
+ *   CPU1                CPU2
+ *   sys_select          receive packet
  *   ...                 ...
  *   __add_wait_queue    update tp->rcv_nxt
  *   ...                 ...

@@ -2264,7 +2263,7 @@ void __sock_tx_timestamp(__u16 tsflags, __u8 *tx_flags);
  * @tsflags:	timestamping flags to use
  * @tx_flags:	completed with instructions for time stamping
  *
- * Note : callers should take care of initial *tx_flags value (usually 0)
+ * Note: callers should take care of initial ``*tx_flags`` value (usually 0)
  */
 static inline void sock_tx_timestamp(const struct sock *sk, __u16 tsflags,
 				     __u8 *tx_flags)

index db1866f2ffcf..4dd594741b6d 100644
@@ -181,7 +181,7 @@ static struct sk_buff *skb_set_peeked(struct sk_buff *skb)
  *
  *	This function will lock the socket if a skb is returned, so
  *	the caller needs to unlock the socket in that case (usually by
- *	calling skb_free_datagram). Returns NULL with *err set to
+ *	calling skb_free_datagram). Returns NULL with @err set to
  *	-EAGAIN if no data was available or to some other value if an
  *	error was detected.
  *

index 79c6aee6af9b..6adc69edfdd6 100644
@@ -2682,9 +2682,12 @@ EXPORT_SYMBOL(release_sock);
  * @sk: socket
  *
  * This version should be used for very small section, where process wont block
- * return false if fast path is taken
+ * return false if fast path is taken:
+ *
  *   sk_lock.slock locked, owned = 0, BH disabled
- * return true if slow path is taken
+ *
+ * return true if slow path is taken:
+ *
  *   sk_lock.slock unlocked, owned = 1, BH enabled
  */
 bool lock_sock_fast(struct sock *sk)

2.9.3
---
 drivers/scsi/scsi_scan.c         |  7 ++++---
 drivers/scsi/scsi_transport_fc.c | 18 ++++++++++--------
 drivers/scsi/scsicam.c           |  4 ++--
 3 files changed, 16 insertions(+), 13 deletions(-)
index 6f7128f49c30..69979574004f 100644
@@ -1051,10 +1051,11 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq,
  *     allocate and set it up by calling scsi_add_lun.
  *
  * Return:
- *     SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device
- *     SCSI_SCAN_TARGET_PRESENT: target responded, but no device is
+ *
+ *   - SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device
+ *   - SCSI_SCAN_TARGET_PRESENT: target responded, but no device is
  *         attached at the LUN
- *     SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized
+ *   - SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized
  **/
 static int scsi_probe_and_add_lun(struct scsi_target *starget,
 				  u64 lun, int *bflagsp,

index d4cf32d55546..1df77453f6b6 100644
@@ -2914,16 +2914,18 @@ EXPORT_SYMBOL(fc_remote_port_add);
  * port is no longer part of the topology. Note: Although a port
  * may no longer be part of the topology, it may persist in the remote
  * ports displayed by the fc_host. We do this under 2 conditions:
+ *
  * 1) If the port was a scsi target, we delay its deletion by "blocking" it.
- *   This allows the port to temporarily disappear, then reappear without
- *   disrupting the SCSI device tree attached to it. During the "blocked"
- *   period the port will still exist.
+ *    This allows the port to temporarily disappear, then reappear without
+ *    disrupting the SCSI device tree attached to it. During the "blocked"
+ *    period the port will still exist.
+ *
  * 2) If the port was a scsi target and disappears for longer than we
- *   expect, we'll delete the port and the tear down the SCSI device tree
- *   attached to it. However, we want to semi-persist the target id assigned
- *   to that port if it eventually does exist. The port structure will
- *   remain (although with minimal information) so that the target id
- *   bindings remails.
+ *    expect, we'll delete the port and the tear down the SCSI device tree
+ *    attached to it. However, we want to semi-persist the target id assigned
+ *    to that port if it eventually does exist. The port structure will
+ *    remain (although with minimal information) so that the target id
+ *    bindings remails.
  *
  * If the remote port is not an FCP Target, it will be fully torn down
  * and deallocated, including the fc_remote_port class device.

index 910f4a7a3924..31273468589c 100644
@@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param);
  * @hds: put heads here
  * @secs: put sectors here
  *
- * Description: determine the BIOS mapping/geometry used to create the partition
- *      table, storing the results in *cyls, *hds, and *secs 
+ * Determine the BIOS mapping/geometry used to create the partition
+ * table, storing the results in @cyls, @hds, and @secs
  *
  * Returns: -1 on failure, 0 on success.
  */

2.9.3
---
 Documentation/DocBook/Makefile |   4 +-
 Documentation/DocBook/sh.tmpl  | 105 -----------------------------------------
 Documentation/conf.py          |   2 +
 Documentation/index.rst        |  11 +++++
 Documentation/sh/conf.py       |  10 ++++
 Documentation/sh/index.rst     |  59 +++++++++++++++++++++++
 6 files changed, 83 insertions(+), 108 deletions(-)
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/sh/conf.py
 create mode 100644 Documentation/sh/index.rst
index 226e5e9fc801..efba7f980895 100644
@@ -6,9 +6,7 @@
 # To add a new book the only step required is to add the book to the
 # list of DOCBOOKS.
 
-DOCBOOKS := \
-	    lsm.xml \
-	    sh.xml
+DOCBOOKS := lsm.xml
 
 ifeq ($(DOCBOOKS),)
 

index dfe14f7525d0..77d47bb1df1d 100644
@@ -375,6 +375,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',
      'The kernel development community', 'manual'),
+    ('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
+     'The kernel development community', 'manual'),
     ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
      'The kernel development community', 'manual'),
     ('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',

index 25c4da41da6b..e9017bb3a6ce 100644
@@ -76,6 +76,17 @@ needed).
    crypto/index
    filesystems/index
 
+Architecture-specific documentation
+-----------------------------------
+
+These books provide programming details about architecture-specific
+implementation.
+
+.. toctree::
+   :maxdepth: 2
+
+   sh/index
+
 Korean translations
 -------------------
 

new file mode 100644
index 000000000000..1eb684a13ac8
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "SuperH architecture implementation manual"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'sh.tex', project,
+     'The kernel development community', 'manual'),
+]

2.9.3
---
 Documentation/PCI/MSI-HOWTO.txt            |  2 +-
 Documentation/admin-guide/README.rst       |  6 ---
 Documentation/doc-guide/index.rst          |  1 -
 Documentation/doc-guide/sphinx.rst         |  5 ---
 Documentation/fb/api.txt                   |  4 +-
 Documentation/gpu/todo.rst                 |  2 +-
 Documentation/kernel-doc-nano-HOWTO.txt    | 65 +++++-------------------------
 Documentation/process/changes.rst          | 26 +++---------
 Documentation/process/howto.rst            |  8 ----
 Documentation/process/kernel-docs.rst      | 34 +---------------
 Documentation/translations/ja_JP/howto.rst |  7 ----
 Documentation/translations/ko_KR/howto.rst |  7 ----
 12 files changed, 21 insertions(+), 146 deletions(-)
index 1e37138027a3..618e13d5e276 100644
@@ -186,7 +186,7 @@ must disable interrupts while the lock is held.  If the device sends
 a different interrupt, the driver will deadlock trying to recursively
 acquire the spinlock.  Such deadlocks can be avoided by using
 spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
-and acquire the lock (see Documentation/DocBook/kernel-locking).
+and acquire the lock (see Documentation/kernel-hacking/locking.rst).
 
 4.5 How to tell whether MSI/MSI-X is enabled on a device
 

index b96e80f79e85..b5343c5aa224 100644
@@ -55,12 +55,6 @@ Documentation
    contains information about the problems, which may result by upgrading
    your kernel.
 
- - The Documentation/DocBook/ subdirectory contains several guides for
-   kernel developers and users.  These guides can be rendered in a
-   number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
-   After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
-   or ``make mandocs`` will render the documentation in the requested format.
-
 Installing the kernel source
 ----------------------------
 

index 6fff4024606e..a7f95d7d3a63 100644
@@ -10,7 +10,6 @@ How to write kernel documentation
    sphinx.rst
    kernel-doc.rst
    parse-headers.rst
-   docbook.rst
 
 .. only::  subproject and html
 

index 731334de3efd..84e8e8a9cbdb 100644
@@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The
 kernel-doc comments have some special structure and formatting, but beyond that
 they are also treated as reStructuredText.
 
-There is also the deprecated DocBook toolchain to generate documentation from
-DocBook XML template files under ``Documentation/DocBook``. The DocBook files
-are to be converted to reStructuredText, and the toolchain is slated to be
-removed.
-
 Finally, there are thousands of plain text documentation files scattered around
 ``Documentation``. Some of these will likely be converted to reStructuredText
 over time, but the bulk of them will remain in plain text.

index d4ff7de85700..d52cf1e3b975 100644
@@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.
 FOURCC definitions are located in the linux/videodev2.h header. However, and
 despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
 and don't require usage of the V4L2 subsystem. FOURCC documentation is
-available in Documentation/DocBook/v4l/pixfmt.xml.
+available in Documentation/media/uapi/v4l/pixfmt.rst.
 
 To select a format, applications set the grayscale field to the desired FOURCC.
 For YUV formats, they should also select the appropriate colorspace by setting
 the colorspace field to one of the colorspaces listed in linux/videodev2.h and
-documented in Documentation/DocBook/v4l/colorspaces.xml.
+documented in Documentation/media/uapi/v4l/colorspaces.rst.
 
 The red, green, blue and transp fields are not used with the FOURCC-based API.
 For forward compatibility reasons applications must zero those fields, and

index 1bdb7356a310..6162d0e9dc28 100644
@@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The
 task would be to clean up interfaces like moving functions around between
 files to better group them and improving the interfaces like dropping return
 values for functions that never fail. Then write kerneldoc for all exported
-functions and an overview section and integrate it all into the drm DocBook.
+functions and an overview section and integrate it all into the drm book.
 
 See https://dri.freedesktop.org/docs/drm/ for what's there already.
 

index e25d63f8c0da..3aed751e0cb5 100644
@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
 
 Linux documentation for functions is transitioning to inline
 documentation via specially-formatted comments near their
-definitions in the source.  These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats.  In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
+definitions in the source.  These comments can be combined with ReST
+files the Documentation/ directory to make enriched documentation, which can
+then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
+In order to convert from ReST format to a format of your choice, you'll need
+Sphinx.
 
 Util-linux
 ----------

@@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
   functionalities required for ``XeLaTex`` to work. For PDF output you'll also
   need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
 
-Other tools
------------
-
-In order to produce documentation from DocBook, you'll also need ``xmlto``.
-Please notice, however, that we're currently migrating all documents to use
-``Sphinx``.
 
 Getting updated software
 ========================

@@ -409,15 +402,6 @@ Quota-tools
 
 - <http://sourceforge.net/projects/linuxquota/>
 
-DocBook Stylesheets
--------------------
-
-- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-
-- <http://cyberelk.net/tim/xmlto/>
 
 Intel P6 microcode
 ------------------

index 1260f60d4cb9..c6875b1db56f 100644
@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
 	make latexdocs
 	make epubdocs
 
-Currently, there are some documents written on DocBook that are in
-the process of conversion to ReST. Such documents will be created in the
-Documentation/DocBook/ directory and can be generated also as
-Postscript or man pages by running::
-
-	make psdocs
-	make mandocs
-
 Becoming A Kernel Developer
 ---------------------------
 

index 05a7857a4a83..b8cac85a4001 100644
@@ -40,50 +40,18 @@ Enjoy!
 Docs at the Linux Kernel tree
 -----------------------------
 
-The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
 The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
 
     * Name: **linux/Documentation**
 
       :Author: Many.
       :Location: Documentation/
-      :Keywords: text files, Sphinx, DocBook.
+      :Keywords: text files, Sphinx.
       :Description: Documentation that comes with the kernel sources,
         inside the Documentation directory. Some pages from this document
         (including this document itself) have been moved there, and might
         be more up to date than the web version.
 
-    * Title: **The Kernel Hacking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-hacking.tmpl
-      :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-        symbols, return conventions.
-      :Description: From the Introduction: "Please understand that I
-        never wanted to write this document, being grossly underqualified,
-        but I always wanted to read it, and this was the only way. I
-        simply explain some best practices, and give reading entry-points
-        into the kernel sources. I avoid implementation details: that's
-        what the code is for, and I ignore whole tracts of useful
-        routines. This document assumes familiarity with C, and an
-        understanding of what the kernel is, and how it is used. It was
-        originally written for the 2.3 kernels, but nearly all of it
-        applies to 2.2 too; 2.0 is slightly different".
-
-    * Title: **Linux Kernel Locking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-locking.tmpl
-      :Keywords: locks, locking, spinlock, semaphore, atomic, race
-        condition, bottom halves, tasklets, softirqs.
-      :Description: The title says it all: document describing the
-        locking system in the Linux Kernel either in uniprocessor or SMP
-        systems.
-      :Notes: "It was originally written for the later (>2.3.47) 2.3
-        kernels, but most of it applies to 2.2 too; 2.0 is slightly
-        different". Freely redistributable under the conditions of the GNU
-        General Public License.
-
 On-line docs
 ------------
 

index 4511eed0fabb..8d7ed0cbbf5f 100644
@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
         make latexdocs
         make epubdocs
 
-現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
-す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
-Postscript または man ページの形式を生成するには以下のようにします - ::
-
-        make psdocs
-        make mandocs
-
 カーネル開発者になるには
 ------------------------
 

index 2333697251dd..f06de9ca41a4 100644
@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
          make latexdocs
          make epubdocs
 
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-
 커널 개발자가 되는 것
 ---------------------
 

2.9.3
---
 drivers/ata/acard-ahci.c    | 2 +-
 drivers/ata/ahci.c          | 2 +-
 drivers/ata/ahci.h          | 2 +-
 drivers/ata/ata_piix.c      | 2 +-
 drivers/ata/libahci.c       | 2 +-
 drivers/ata/libata-core.c   | 2 +-
 drivers/ata/libata-eh.c     | 2 +-
 drivers/ata/libata-scsi.c   | 2 +-
 drivers/ata/libata-sff.c    | 2 +-
 drivers/ata/libata.h        | 2 +-
 drivers/ata/pata_pdc2027x.c | 2 +-
 drivers/ata/pdc_adma.c      | 2 +-
 drivers/ata/sata_nv.c       | 2 +-
 drivers/ata/sata_promise.c  | 2 +-
 drivers/ata/sata_promise.h  | 2 +-
 drivers/ata/sata_qstor.c    | 2 +-
 drivers/ata/sata_sil.c      | 2 +-
 drivers/ata/sata_sis.c      | 2 +-
 drivers/ata/sata_svw.c      | 2 +-
 drivers/ata/sata_sx4.c      | 2 +-
 drivers/ata/sata_uli.c      | 2 +-
 drivers/ata/sata_via.c      | 2 +-
 drivers/ata/sata_vsc.c      | 2 +-
 include/linux/ata.h         | 2 +-
 include/linux/libata.h      | 2 +-
 25 files changed, 25 insertions(+), 25 deletions(-)
index ed6a30cd681a..940ddbc59aa7 100644
@@ -25,7 +25,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

index 2fc52407306c..fd712e0e9d87 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

index 5db6ab261643..30f67a1a4f54 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

index ffbe625e6fd2..8401c3b5be92 100644
@@ -33,7 +33,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available at http://developer.intel.com/
  *

index 3159f9e66d8f..6154f0e2b81a 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

index 2d83b8c75965..55aaa2e4c683 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/

index ef68232b5222..7e33e200aae5 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/

index dcd38d9e9804..b0866f040d1f 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from
  *  - http://www.t10.org/

index 274d6d7193d7..052921352f31 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/

index 120fce0befd3..5afe35baf61b 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 

index d9ef9e276225..82bfd51692f3 100644
@@ -17,7 +17,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware information only available under NDA.
  *

index 64d682c6ee57..f1e873a37465 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *
  *  Supports ATA disks in single-packet ADMA mode.

index 734f563b8d37..8c683ddd0f58 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  No hardware documentation available outside of NVIDIA.
  *  This driver programs the NVIDIA SATA controller in a similar

index 0fa211e2831c..d032bf657f70 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware information only available under NDA.
  *

index 00d6000e546f..61633ef5ed72 100644
@@ -20,7 +20,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 

index af987a4f33d1..1fe941688e95 100644
@@ -23,7 +23,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 

index 29bcff086bce..ed76f070d21e 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Documentation for SiI 3112:
  *  http://gkernel.sourceforge.net/specs/sii/3112A_SiI-DS-0095-B2.pdf.bz2

index d1637ac40a73..30f4f35f36d4 100644
@@ -24,7 +24,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *

index ff614be55d0f..0fd6ac7e57ba 100644
@@ -30,7 +30,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *

index 48301cb3a316..405e606a234d 100644
@@ -24,7 +24,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *

index 08f98c3ed5c8..4f6e8d8156de 100644
@@ -18,7 +18,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *

index f3f538eec7b3..22e96fc77d09 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *

index 183eb52085df..9648127cca70 100644
@@ -26,7 +26,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Vitesse hardware documentation presumably available under NDA.
  *  Intel 31244 (same hardware interface) documentation presumably

index ad7d9ee89ff0..73fe18edfdaf 100644
@@ -20,7 +20,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/
  *

index c9a69fc8821e..9e6633235ad7 100644
@@ -19,7 +19,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 

2.9.3
---
 arch/ia64/include/asm/io.h | 2 +-
 arch/ia64/sn/kernel/iomv.c | 2 +-
 drivers/scsi/qla1280.c     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
index 5de673ac9cb1..a2540e21f919 100644
@@ -117,7 +117,7 @@ extern int valid_mmap_phys_addr_range (unsigned long pfn, size_t count);
  * following the barrier will arrive after all previous writes.  For most
  * ia64 platforms, this is a simple 'mf.a' instruction.
  *
- * See Documentation/DocBook/deviceiobook.tmpl for more information.
+ * See Documentation/driver-api/device-io.rst for more information.
  */
 static inline void ___ia64_mmiowb(void)
 {

index c77ebdf98119..2b22a71663c1 100644
@@ -63,7 +63,7 @@ EXPORT_SYMBOL(sn_io_addr);
 /**
  * __sn_mmiowb - I/O space memory barrier
  *
- * See arch/ia64/include/asm/io.h and Documentation/DocBook/deviceiobook.tmpl
+ * See arch/ia64/include/asm/io.h and Documentation/driver-api/device-io.rst
  * for details.
  *
  * On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear.

index 634254a52301..8a29fb09db14 100644
@@ -3390,7 +3390,7 @@ qla1280_isp_cmd(struct scsi_qla_host *ha)
 	 *    On PCI bus, order reverses and write of 6 posts, then index 5,
 	 *       causing chip to issue full queue of stale commands
 	 * The mmiowb() prevents future writes from crossing the barrier.
-	 * See Documentation/DocBook/deviceiobook.tmpl for more information.
+	 * See Documentation/driver-api/device-io.rst for more information.
 	 */
 	WRT_REG_WORD(&reg->mailbox4, ha->req_ring_index);
 	mmiowb();

2.9.3
---
 drivers/usb/gadget/Kconfig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
index c164d6b788c3..b3c879b75a39 100644
@@ -41,7 +41,7 @@ menuconfig USB_GADGET
 	   don't have this kind of hardware (except maybe inside Linux PDAs).
 
 	   For more information, see <http://www.linux-usb.org/gadget> and
-	   the kernel DocBook documentation for this API.
+	   the kernel documentation for this API.
 
 if USB_GADGET
 

---
 fs/eventfd.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
index 68b9fffcb2c8..beac8175de19 100644
@@ -215,8 +215,8 @@ EXPORT_SYMBOL_GPL(eventfd_ctx_remove_wait_queue);
  *
  * Returns %0 if successful, or the following error codes:
  *
- * -EAGAIN      : The operation would have blocked but @no_wait was non-zero.
- * -ERESTARTSYS : A signal interrupted the wait operation.
+ *  - -EAGAIN      : The operation would have blocked but @no_wait was non-zero.
+ *  - -ERESTARTSYS : A signal interrupted the wait operation.
  *
  * If @no_wait is zero, the function might sleep until the eventfd internal
  * counter becomes greater than zero.

2.9.3
---
 Documentation/kernel-hacking/locking.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)
index b70c2c4eb147..f937c0fd11aa 100644
@@ -93,13 +93,13 @@ Locking in the Linux Kernel
 ===========================
 
 If I could give you one piece of advice: never sleep with anyone crazier
-than yourself. But if I had to give you advice on locking: *keep it
-simple*.
+than yourself. But if I had to give you advice on locking: **keep it
+simple**.
 
 Be reluctant to introduce new locks.
 
 Strangely enough, this last one is the exact reverse of my advice when
-you *have* slept with someone crazier than yourself. And you should
+you **have** slept with someone crazier than yourself. And you should
 think about getting a big dog.
 
 Two Main Types of Kernel Locks: Spinlocks and Mutexes

@@ -311,7 +311,7 @@ Pete Zaitcev gives the following summary:
 Table of Minimum Requirements
 -----------------------------
 
-The following table lists the *minimum* locking requirements between
+The following table lists the **minimum** locking requirements between
 various contexts. In some cases, the same context can only be running on
 one CPU at a time, so no locking is required for that context (eg. a
 particular thread can only run on one CPU at a time, but if it needs

@@ -703,7 +703,7 @@ reference count, but they are more complicated.
 Using Atomic Operations For The Reference Count
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In practice, ``atomic_t`` would usually be used for refcnt. There are a
+In practice, :c:type:`atomic_t` would usually be used for refcnt. There are a
 number of atomic operations defined in ``include/asm/atomic.h``: these
 are guaranteed to be seen atomically from all CPUs in the system, so no
 lock is required. In this case, it is simpler than using spinlocks,

@@ -1321,7 +1321,7 @@ from user context, and can sleep.
 
    -  :c:func:`put_user()`
 
--  ``kmalloc(GFP_KERNEL)``
+-  :c:func:`kmalloc(GFP_KERNEL) <kmalloc>`
 
 -  :c:func:`mutex_lock_interruptible()` and
    :c:func:`mutex_lock()`

@@ -1431,10 +1431,10 @@ tasklet
 timer
   A dynamically-registrable software interrupt, which is run at (or close
   to) a given time. When running, it is just like a tasklet (in fact, they
-  are called from the TIMER_SOFTIRQ).
+  are called from the ``TIMER_SOFTIRQ``).
 
 UP
-  Uni-Processor: Non-SMP. (CONFIG_SMP=n).
+  Uni-Processor: Non-SMP. (``CONFIG_SMP=n``).
 
 User Context
   The kernel executing on behalf of a particular process (ie. a system

2.9.3
---
 fs/fs-writeback.c | 12 +++++++-----
 fs/mpage.c        |  1 +
 fs/namei.c        |  1 +
 3 files changed, 9 insertions(+), 5 deletions(-)
index 63ee2940775c..8b426f83909f 100644
@@ -2052,11 +2052,13 @@ static noinline void block_dump___mark_inode_dirty(struct inode *inode)
 }
 
 /**
- *	__mark_inode_dirty -	internal function
- *	@inode: inode to mark
- *	@flags: what kind of dirty (i.e. I_DIRTY_SYNC)
- *	Mark an inode as dirty. Callers should use mark_inode_dirty or
- *  	mark_inode_dirty_sync.
+ * __mark_inode_dirty -	internal function
+ *
+ * @inode: inode to mark
+ * @flags: what kind of dirty (i.e. I_DIRTY_SYNC)
+ *
+ * Mark an inode as dirty. Callers should use mark_inode_dirty or
+ * mark_inode_dirty_sync.
  *
  * Put the inode on the super block's dirty list.
  *

index baff8f820c29..4760a0c09a4e 100644
@@ -344,6 +344,7 @@ do_mpage_readpage(struct bio *bio, struct page *page, unsigned nr_pages,
  *
  * So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be
  * submitted in the following order:
+ *
  * 	12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16
  *
  * because the indirect block has to be read to get the mappings of blocks

index 7286f87ce863..b5af8228e2d9 100644
@@ -4300,6 +4300,7 @@ SYSCALL_DEFINE2(link, const char __user *, oldname, const char __user *, newname
  * The worst of all namespace operations - renaming directory. "Perverted"
  * doesn't even start to describe it. Somebody in UCB had a heck of a trip...
  * Problems:
+ *
  *	a) we can get into loop creation.
  *	b) race potential - two innocent renames can create a loop together.
  *	   That's where 4.4 screws up. Current fix: serialization on

2.9.3
---
 Documentation/kernel-hacking/locking.rst | 66 ++++++++++++++++----------------
 1 file changed, 34 insertions(+), 32 deletions(-)
index 17774b1f7587..b70c2c4eb147 100644
@@ -29,43 +29,45 @@ In a normal program, you can increment a counter like so:
 
 This is what they would expect to happen:
 
-+------------------------------------+------------------------------------+
-| Instance 1                         | Instance 2                         |
-+====================================+====================================+
-| read very_important_count (5)      |                                    |
-+------------------------------------+------------------------------------+
-| add 1 (6)                          |                                    |
-+------------------------------------+------------------------------------+
-| write very_important_count (6)     |                                    |
-+------------------------------------+------------------------------------+
-|                                    | read very_important_count (6)      |
-+------------------------------------+------------------------------------+
-|                                    | add 1 (7)                          |
-+------------------------------------+------------------------------------+
-|                                    | write very_important_count (7)     |
-+------------------------------------+------------------------------------+
 
-Table: Expected Results
+.. table:: Expected Results
+
+  +------------------------------------+------------------------------------+
+  | Instance 1                         | Instance 2                         |
+  +====================================+====================================+
+  | read very_important_count (5)      |                                    |
+  +------------------------------------+------------------------------------+
+  | add 1 (6)                          |                                    |
+  +------------------------------------+------------------------------------+
+  | write very_important_count (6)     |                                    |
+  +------------------------------------+------------------------------------+
+  |                                    | read very_important_count (6)      |
+  +------------------------------------+------------------------------------+
+  |                                    | add 1 (7)                          |
+  +------------------------------------+------------------------------------+
+  |                                    | write very_important_count (7)     |
+  +------------------------------------+------------------------------------+
 
 This is what might happen:
 
-+------------------------------------+------------------------------------+
-| Instance 1                         | Instance 2                         |
-+====================================+====================================+
-| read very_important_count (5)      |                                    |
-+------------------------------------+------------------------------------+
-|                                    | read very_important_count (5)      |
-+------------------------------------+------------------------------------+
-| add 1 (6)                          |                                    |
-+------------------------------------+------------------------------------+
-|                                    | add 1 (6)                          |
-+------------------------------------+------------------------------------+
-| write very_important_count (6)     |                                    |
-+------------------------------------+------------------------------------+
-|                                    | write very_important_count (6)     |
-+------------------------------------+------------------------------------+
+.. table:: Possible Results
+
+  +------------------------------------+------------------------------------+
+  | Instance 1                         | Instance 2                         |
+  +====================================+====================================+
+  | read very_important_count (5)      |                                    |
+  +------------------------------------+------------------------------------+
+  |                                    | read very_important_count (5)      |
+  +------------------------------------+------------------------------------+
+  | add 1 (6)                          |                                    |
+  +------------------------------------+------------------------------------+
+  |                                    | add 1 (6)                          |
+  +------------------------------------+------------------------------------+
+  | write very_important_count (6)     |                                    |
+  +------------------------------------+------------------------------------+
+  |                                    | write very_important_count (6)     |
+  +------------------------------------+------------------------------------+
 
-Table: Possible Results
 
 Race Conditions and Critical Regions
 ------------------------------------

2.9.3
---
 Documentation/driver-api/mtdnand.rst | 3 ---
 drivers/mtd/nand/nand_base.c         | 7 +++++--
 include/linux/mtd/nand.h             | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)
index 7c19795ebb4a..e9afa586d15e 100644
@@ -970,9 +970,6 @@ hints" for an explanation.
 .. kernel-doc:: drivers/mtd/nand/nand_base.c
    :export:
 
-.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
-   :export:
-
 .. kernel-doc:: drivers/mtd/nand/nand_ecc.c
    :export:
 

index b0524f8accb6..c8988c01e0d7 100644
@@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
  * specify how to write bad block markers to OOB (chip->block_markbad).
  *
  * We try operations in the following order:
+ *
  *  (1) erase the affected block, to allow OOB marker to be written cleanly
  *  (2) write bad block marker to OOB area of affected block (unless flag
  *      NAND_BBT_NO_OOB_BBM is present)
  *  (3) update the BBT
+ *
  * Note that we retain the first error encountered in (2) or (3), finish the
  * procedures, and dump the error in the end.
 */

@@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
  * @mtd: mtd info
  * @ofs: offset to start unlock from
  * @len: length to unlock
- * @invert: when = 0, unlock the range of blocks within the lower and
+ * @invert:
+ *        - when = 0, unlock the range of blocks within the lower and
  *                    upper boundary address
- *          when = 1, unlock the range of blocks outside the boundaries
+ *        - when = 1, unlock the range of blocks outside the boundaries
  *                    of the lower and upper boundary address
  *
  * Returs unlock status.

index 9591e0fbe5bd..3d5b20379ba3 100644
@@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
  *			Minimum amount of bit errors per @ecc_step_ds guaranteed
  *			to be correctable. If unknown, set to zero.
  * @ecc_step_ds:	[INTERN] ECC step required by the @ecc_strength_ds,
- *                      also from the datasheet. It is the recommended ECC step
+ *			also from the datasheet. It is the recommended ECC step
  *			size, if known; if unknown, set to zero.
  * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
  *			      set to the actually used ONFI mode if the chip is

2.9.3
---
 Documentation/conf.py       |  2 ++
 Documentation/sound/conf.py | 10 ++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 Documentation/sound/conf.py
index 1d461f0c1cd0..bca751960dec 100644
@@ -371,6 +371,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',
      'The kernel development community', 'manual'),
+    ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
+     'The kernel development community', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

new file mode 100644
index 000000000000..3f1fc5e74e7b
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Sound Subsystem Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'sound.tex', project,
+     'The kernel development community', 'manual'),
+]

2.9.3
---
 Documentation/00-INDEX               |   4 --
 Documentation/DocBook/.gitignore     |  17 -----
 Documentation/DocBook/Makefile       |   1 -
 Documentation/DocBook/stylesheet.xsl |  11 ---
 Documentation/Makefile               | 125 +++++++++++++++++++++++++++++++++
 Documentation/Makefile.sphinx        | 130 -----------------------------------
 Documentation/doc-guide/docbook.rst  |  90 ------------------------
 Makefile                             |  11 ++-
 scripts/Makefile                     |   9 +--
 scripts/check-lc_ctype.c             |  11 ---
 10 files changed, 132 insertions(+), 277 deletions(-)
 delete mode 100644 Documentation/DocBook/.gitignore
 delete mode 100644 Documentation/DocBook/Makefile
 delete mode 100644 Documentation/DocBook/stylesheet.xsl
 delete mode 100644 Documentation/Makefile.sphinx
 delete mode 100644 Documentation/doc-guide/docbook.rst
 delete mode 100644 scripts/check-lc_ctype.c
index 8c2a66e176b9..d0165461b024 100644
@@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
 	- How to do DMA with ISA (and LPC) devices.
 DMA-attributes.txt
 	- listing of the various possible attributes a DMA region can have
-DocBook/
-	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
 IPMI.txt

@@ -40,8 +38,6 @@ Intel-IOMMU.txt
 	- basic info on the Intel IOMMU virtualization support.
 Makefile
 	- It's not of interest for those who aren't touching the build system.
-Makefile.sphinx
-	- It's not of interest for those who aren't touching the build system.
 PCI/
 	- info related to PCI drivers.
 RCU/

deleted file mode 100644
index e05da3f7aa21..000000000000
@@ -1,17 +0,0 @@
-*.xml
-*.ps
-*.pdf
-*.html
-*.9.gz
-*.9
-*.aux
-*.dvi
-*.log
-*.out
-*.png
-*.gif
-*.svg
-*.proc
-*.db
-media-indices.tmpl
-media-entities.tmpl

deleted file mode 100644
index 8b137891791f..000000000000
@@ -1 +0,0 @@
-

deleted file mode 100644
index 3bf4ecf3d760..000000000000
@@ -1,11 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
-<param name="chunk.quietly">1</param>
-<param name="funcsynopsis.style">ansi</param>
-<param name="funcsynopsis.tabular.threshold">80</param>
-<param name="callout.graphics">0</param>
-<!-- <param name="paper.type">A4</param> -->
-<param name="generate.consistent.ids">1</param>
-<param name="generate.section.toc.level">2</param>
-<param name="use.id.as.filename">1</param>
-</stylesheet>

index 220121fdca4d..80be98ccca60 100644
@@ -1298,7 +1298,7 @@ clean: archclean vmlinuxclean
 #
 mrproper: rm-dirs  := $(wildcard $(MRPROPER_DIRS))
 mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
-mrproper-dirs      := $(addprefix _mrproper_,Documentation/DocBook scripts)
+mrproper-dirs      := $(addprefix _mrproper_,scripts)
 
 PHONY += $(mrproper-dirs) mrproper archmrproper
 $(mrproper-dirs):

@@ -1400,9 +1400,7 @@ help:
 	@$(MAKE) $(build)=$(package-dir) help
 	@echo  ''
 	@echo  'Documentation targets:'
-	@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
-	@echo  ''
-	@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
+	@$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
 	@echo  ''
 	@echo  'Architecture specific targets ($(SRCARCH)):'
 	@$(if $(archhelp),$(archhelp),\

@@ -1453,9 +1451,8 @@ $(help-board-dirs): help-%:
 DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
-	$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
-	$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
-	$(Q)$(MAKE) $(build)=Documentation/DocBook $@
+	$(Q)$(MAKE) $(build)=scripts build_docproc
+	$(Q)$(MAKE) $(build)=Documentation $@
 
 else # KBUILD_EXTMOD
 

index 1d80897a9644..55550e4141c4 100644
@@ -6,8 +6,7 @@
 # pnmttologo:    Convert pnm files to logo files
 # conmakehash:   Create chartable
 # conmakehash:	 Create arrays for initializing the kernel console tables
-# docproc:       Used in Documentation/DocBook
-# check-lc_ctype: Used in Documentation/DocBook
+# docproc:       Used in Documentation/
 
 HOST_EXTRACFLAGS += -I$(srctree)/tools/include
 

@@ -29,16 +28,14 @@ HOSTLOADLIBES_extract-cert = -lcrypto
 always		:= $(hostprogs-y) $(hostprogs-m)
 
 # The following hostprogs-y programs are only build on demand
-hostprogs-y += unifdef docproc check-lc_ctype
+hostprogs-y += unifdef docproc
 
 # These targets are used internally to avoid "is up to date" messages
-PHONY += build_unifdef build_docproc build_check-lc_ctype
+PHONY += build_unifdef build_docproc
 build_unifdef: $(obj)/unifdef
 	@:
 build_docproc: $(obj)/docproc
 	@:
-build_check-lc_ctype: $(obj)/check-lc_ctype
-	@:
 
 subdir-$(CONFIG_MODVERSIONS) += genksyms
 subdir-y                     += mod

deleted file mode 100644
index 9097ff5449fb..000000000000
@@ -1,11 +0,0 @@
-/*
- * Check that a specified locale works as LC_CTYPE.  Used by the
- * DocBook build system to probe for C.UTF-8 support.
- */
-
-#include <locale.h>
-
-int main(void)
-{
-	return !setlocale(LC_CTYPE, "");
-}

2.9.3
 Documentation/00-INDEX                     |    6 +-
 Documentation/DocBook/.gitignore           |   17 -
 Documentation/DocBook/Makefile             |  282 ----
 Documentation/DocBook/filesystems.tmpl     |  381 -----
 Documentation/DocBook/kernel-hacking.tmpl  | 1312 -----------------
 Documentation/DocBook/kernel-locking.tmpl  | 2151 ----------------------------
 Documentation/DocBook/kgdb.tmpl            |  918 ------------
 Documentation/DocBook/libata.tmpl          | 1625 ---------------------
 Documentation/DocBook/librs.tmpl           |  289 ----
 Documentation/DocBook/lsm.tmpl             |  265 ----
 Documentation/DocBook/mtdnand.tmpl         | 1291 -----------------
 Documentation/DocBook/networking.tmpl      |  111 --
 Documentation/DocBook/rapidio.tmpl         |  155 --
 Documentation/DocBook/s390-drivers.tmpl    |  161 ---
 Documentation/DocBook/scsi.tmpl            |  409 ------
 Documentation/DocBook/sh.tmpl              |  105 --
 Documentation/DocBook/stylesheet.xsl       |   11 -
 Documentation/DocBook/w1.tmpl              |  101 --
 Documentation/DocBook/z8530book.tmpl       |  371 -----
 Documentation/Makefile                     |  125 ++
 Documentation/Makefile.sphinx              |  130 --
 Documentation/PCI/MSI-HOWTO.txt            |    2 +-
 Documentation/admin-guide/README.rst       |    6 -
 Documentation/conf.py                      |   37 +-
 Documentation/core-api/index.rst           |    1 +
 Documentation/core-api/librs.rst           |  212 +++
 Documentation/crypto/conf.py               |   10 +
 Documentation/dev-tools/index.rst          |    1 +
 Documentation/dev-tools/kgdb.rst           |  907 ++++++++++++
 Documentation/doc-guide/docbook.rst        |   90 --
 Documentation/doc-guide/index.rst          |    1 -
 Documentation/doc-guide/kernel-doc.rst     |   10 +
 Documentation/doc-guide/sphinx.rst         |    5 -
 Documentation/driver-api/index.rst         |    6 +
 Documentation/driver-api/libata.rst        | 1031 +++++++++++++
 Documentation/driver-api/mtdnand.rst       | 1007 +++++++++++++
 Documentation/driver-api/rapidio.rst       |  107 ++
 Documentation/driver-api/s390-drivers.rst  |  111 ++
 Documentation/driver-api/scsi.rst          |  344 +++++
 Documentation/driver-api/w1.rst            |   70 +
 Documentation/fb/api.txt                   |    4 +-
 Documentation/filesystems/conf.py          |   10 +
 Documentation/filesystems/index.rst        |  317 ++++
 Documentation/gpu/todo.rst                 |    2 +-
 Documentation/index.rst                    |   14 +
 Documentation/kernel-doc-nano-HOWTO.txt    |   65 +-
 Documentation/kernel-hacking/conf.py       |   10 +
 Documentation/kernel-hacking/hacking.rst   |  811 +++++++++++
 Documentation/kernel-hacking/index.rst     |    9 +
 Documentation/kernel-hacking/locking.rst   | 1446 +++++++++++++++++++
 Documentation/lsm.txt                      |  201 +++
 Documentation/networking/conf.py           |   10 +
 Documentation/networking/index.rst         |   18 +
 Documentation/networking/kapi.rst          |  147 ++
 Documentation/networking/z8530book.rst     |  256 ++++
 Documentation/process/changes.rst          |   26 +-
 Documentation/process/howto.rst            |    8 -
 Documentation/process/kernel-docs.rst      |   34 +-
 Documentation/sh/conf.py                   |   10 +
 Documentation/sh/index.rst                 |   59 +
 Documentation/sound/conf.py                |   10 +
 Documentation/sphinx/tmplcvt               |   28 -
 Documentation/translations/ja_JP/howto.rst |    7 -
 Documentation/translations/ko_KR/howto.rst |    7 -
 MAINTAINERS                                |    5 +-
 Makefile                                   |   11 +-
 arch/ia64/include/asm/io.h                 |    2 +-
 arch/ia64/sn/kernel/iomv.c                 |    2 +-
 drivers/ata/acard-ahci.c                   |    2 +-
 drivers/ata/ahci.c                         |    2 +-
 drivers/ata/ahci.h                         |    2 +-
 drivers/ata/ata_piix.c                     |    2 +-
 drivers/ata/libahci.c                      |    2 +-
 drivers/ata/libata-core.c                  |    2 +-
 drivers/ata/libata-eh.c                    |    2 +-
 drivers/ata/libata-scsi.c                  |    9 +-
 drivers/ata/libata-sff.c                   |    2 +-
 drivers/ata/libata.h                       |    2 +-
 drivers/ata/pata_pdc2027x.c                |    2 +-
 drivers/ata/pdc_adma.c                     |    2 +-
 drivers/ata/sata_nv.c                      |    2 +-
 drivers/ata/sata_promise.c                 |    2 +-
 drivers/ata/sata_promise.h                 |    2 +-
 drivers/ata/sata_qstor.c                   |    2 +-
 drivers/ata/sata_sil.c                     |    2 +-
 drivers/ata/sata_sis.c                     |    2 +-
 drivers/ata/sata_svw.c                     |    2 +-
 drivers/ata/sata_sx4.c                     |    2 +-
 drivers/ata/sata_uli.c                     |    2 +-
 drivers/ata/sata_via.c                     |    2 +-
 drivers/ata/sata_vsc.c                     |    2 +-
 drivers/mtd/nand/nand_base.c               |    7 +-
 drivers/net/phy/phy.c                      |    1 +
 drivers/scsi/qla1280.c                     |    2 +-
 drivers/scsi/scsi_scan.c                   |    7 +-
 drivers/scsi/scsi_transport_fc.c           |   18 +-
 drivers/scsi/scsicam.c                     |    4 +-
 drivers/usb/gadget/Kconfig                 |    2 +-
 fs/debugfs/file.c                          |    2 +-
 fs/debugfs/inode.c                         |    2 +-
 fs/eventfd.c                               |    4 +-
 fs/fs-writeback.c                          |   12 +-
 fs/jbd2/transaction.c                      |   42 +-
 fs/mpage.c                                 |    1 +
 fs/namei.c                                 |    1 +
 include/linux/ata.h                        |    2 +-
 include/linux/debugfs.h                    |    2 +-
 include/linux/libata.h                     |    2 +-
 include/linux/mtd/nand.h                   |    2 +-
 include/linux/mutex.h                      |    6 +-
 include/linux/netdevice.h                  |    9 +-
 include/linux/skbuff.h                     |    2 +-
 include/net/sock.h                         |    9 +-
 kernel/futex.c                             |   40 +-
 kernel/irq/chip.c                          |    2 +-
 kernel/irq/handle.c                        |    2 +-
 kernel/irq/irqdesc.c                       |    2 +-
 kernel/locking/mutex.c                     |    6 +-
 lib/Kconfig.debug                          |    2 +-
 lib/Kconfig.kgdb                           |    2 +-
 net/core/datagram.c                        |    2 +-
 net/core/sock.c                            |    7 +-
 scripts/Makefile                           |    9 +-
 scripts/check-lc_ctype.c                   |   11 -
 124 files changed, 7469 insertions(+), 10511 deletions(-)
 delete mode 100644 Documentation/DocBook/.gitignore
 delete mode 100644 Documentation/DocBook/Makefile
 delete mode 100644 Documentation/DocBook/filesystems.tmpl
 delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl
 delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
 delete mode 100644 Documentation/DocBook/kgdb.tmpl
 delete mode 100644 Documentation/DocBook/libata.tmpl
 delete mode 100644 Documentation/DocBook/librs.tmpl
 delete mode 100644 Documentation/DocBook/lsm.tmpl
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 delete mode 100644 Documentation/DocBook/networking.tmpl
 delete mode 100644 Documentation/DocBook/rapidio.tmpl
 delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
 delete mode 100644 Documentation/DocBook/scsi.tmpl
 delete mode 100644 Documentation/DocBook/sh.tmpl
 delete mode 100644 Documentation/DocBook/stylesheet.xsl
 delete mode 100644 Documentation/DocBook/w1.tmpl
 delete mode 100644 Documentation/DocBook/z8530book.tmpl
 delete mode 100644 Documentation/Makefile.sphinx
 create mode 100644 Documentation/core-api/librs.rst
 create mode 100644 Documentation/crypto/conf.py
 create mode 100644 Documentation/dev-tools/kgdb.rst
 delete mode 100644 Documentation/doc-guide/docbook.rst
 create mode 100644 Documentation/driver-api/libata.rst
 create mode 100644 Documentation/driver-api/mtdnand.rst
 create mode 100644 Documentation/driver-api/rapidio.rst
 create mode 100644 Documentation/driver-api/s390-drivers.rst
 create mode 100644 Documentation/driver-api/scsi.rst
 create mode 100644 Documentation/driver-api/w1.rst
 create mode 100644 Documentation/filesystems/conf.py
 create mode 100644 Documentation/filesystems/index.rst
 create mode 100644 Documentation/kernel-hacking/conf.py
 create mode 100644 Documentation/kernel-hacking/hacking.rst
 create mode 100644 Documentation/kernel-hacking/index.rst
 create mode 100644 Documentation/kernel-hacking/locking.rst
 create mode 100644 Documentation/lsm.txt
 create mode 100644 Documentation/networking/conf.py
 create mode 100644 Documentation/networking/index.rst
 create mode 100644 Documentation/networking/kapi.rst
 create mode 100644 Documentation/networking/z8530book.rst
 create mode 100644 Documentation/sh/conf.py
 create mode 100644 Documentation/sh/index.rst
 create mode 100644 Documentation/sound/conf.py
 delete mode 100755 Documentation/sphinx/tmplcvt
 delete mode 100644 scripts/check-lc_ctype.c
2.9.3
---
 Documentation/DocBook/Makefile         |   2 +-
 Documentation/DocBook/filesystems.tmpl | 381 ---------------------------------
 Documentation/conf.py                  |   2 +
 Documentation/filesystems/conf.py      |  10 +
 Documentation/filesystems/index.rst    | 314 +++++++++++++++++++++++++++
 Documentation/index.rst                |   1 +
 6 files changed, 328 insertions(+), 382 deletions(-)
 delete mode 100644 Documentation/DocBook/filesystems.tmpl
 create mode 100644 Documentation/filesystems/conf.py
 create mode 100644 Documentation/filesystems/index.rst
index b9d2b88b9905..2f767e30b59e 100644
@@ -8,7 +8,7 @@
 
 DOCBOOKS := z8530book.xml  \
 	    networking.xml \
-	    filesystems.xml lsm.xml \
+	    lsm.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    s390-drivers.xml scsi.xml \
 	    sh.xml w1.xml

index 2e215477edf5..ad9a4781b330 100644
@@ -359,6 +359,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
      'The kernel development community', 'manual'),
+    ('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
+     'The kernel development community', 'manual'),
     ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
      'The kernel development community', 'manual'),
     ('input/index', 'linux-input.tex', 'The Linux input driver subsystem',

new file mode 100644
index 000000000000..ea44172af5c4
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Filesystems API"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'filesystems.tex', project,
+     'The kernel development community', 'manual'),
+]

index 01a24486ea5f..dae365f3820e 100644
@@ -73,6 +73,7 @@ needed).
    security/index
    sound/index
    crypto/index
+   filesystems/index
 
 Korean translations
 -------------------

2.9.3
---
 Documentation/DocBook/Makefile    |   2 +-
 Documentation/DocBook/kgdb.tmpl   | 918 -------------------------------------
 Documentation/dev-tools/index.rst |   1 +
 Documentation/dev-tools/kgdb.rst  | 930 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 932 insertions(+), 919 deletions(-)
 delete mode 100644 Documentation/DocBook/kgdb.tmpl
 create mode 100644 Documentation/dev-tools/kgdb.rst
index 9df94f7c2003..b9d2b88b9905 100644
@@ -8,7 +8,7 @@
 
 DOCBOOKS := z8530book.xml  \
 	    networking.xml \
-	    filesystems.xml lsm.xml kgdb.xml \
+	    filesystems.xml lsm.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    s390-drivers.xml scsi.xml \
 	    sh.xml w1.xml

index 07d881147ef3..4ac991dbddb7 100644
@@ -23,6 +23,7 @@ whole; patches welcome!
    kmemleak
    kmemcheck
    gdb-kernel-debugging
+   kgdb
 
 
 .. only::  subproject and html

2.9.3
---
 Documentation/filesystems/index.rst | 76 +++++++++++++++++++------------------
 1 file changed, 40 insertions(+), 36 deletions(-)
index 3bc82e9d22f0..148becd91cba 100644
@@ -125,27 +125,27 @@ Details
 The journalling layer is easy to use. You need to first of all create a
 journal_t data structure. There are two calls to do this dependent on
 how you decide to allocate the physical media on which the journal
-resides. The jbd2_journal_init_inode() call is for journals stored in
-filesystem inodes, or the jbd2_journal_init_dev() call can be used
+resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
+filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
 for journal stored on a raw device (in a continuous range of blocks). A
 journal_t is a typedef for a struct pointer, so when you are finally
-finished make sure you call jbd2_journal_destroy() on it to free up
+finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
 any used kernel memory.
 
 Once you have got your journal_t object you need to 'mount' or load the
 journal file. The journalling layer expects the space for the journal
 was already allocated and initialized properly by the userspace tools.
-When loading the journal you must call jbd2_journal_load() to process
+When loading the journal you must call :c:func:`jbd2_journal_load` to process
 journal contents. If the client file system detects the journal contents
 does not need to be processed (or even need not have valid contents), it
-may call jbd2_journal_wipe() to clear the journal contents before
-calling jbd2_journal_load().
+may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
+calling :c:func:`jbd2_journal_load`.
 
 Note that jbd2_journal_wipe(..,0) calls
-jbd2_journal_skip_recovery() for you if it detects any outstanding
-transactions in the journal and similarly jbd2_journal_load() will
-call jbd2_journal_recover() if necessary. I would advise reading
-ext4_load_journal() in fs/ext4/super.c for examples on this stage.
+:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
+transactions in the journal and similarly :c:func:`jbd2_journal_load` will
+call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
+:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
 
 Now you can go ahead and start modifying the underlying filesystem.
 Almost.

@@ -154,54 +154,57 @@ You still need to actually journal your filesystem changes, this is done
 by wrapping them into transactions. Additionally you also need to wrap
 the modification of each of the buffers with calls to the journal layer,
 so it knows what the modifications you are actually making are. To do
-this use jbd2_journal_start() which returns a transaction handle.
+this use :c:func:`jbd2_journal_start` which returns a transaction handle.
 
-jbd2_journal_start() and its counterpart jbd2_journal_stop(), which
-indicates the end of a transaction are nestable calls, so you can
+:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
+which indicates the end of a transaction are nestable calls, so you can
 reenter a transaction if necessary, but remember you must call
-jbd2_journal_stop() the same number of times as jbd2_journal_start()
-before the transaction is completed (or more accurately leaves the
-update phase). Ext4/VFS makes use of this feature to simplify handling
-of inode dirtying, quota support, etc.
+:c:func:`jbd2_journal_stop` the same number of times as
+:c:func:`jbd2_journal_start` before the transaction is completed (or more
+accurately leaves the update phase). Ext4/VFS makes use of this feature to
+simplify handling of inode dirtying, quota support, etc.
 
 Inside each transaction you need to wrap the modifications to the
 individual buffers (blocks). Before you start to modify a buffer you
-need to call jbd2_journal_get_{create,write,undo}_access() as
-appropriate, this allows the journalling layer to copy the unmodified
+need to call :c:func:`jbd2_journal_get_create_access()` /
+:c:func:`jbd2_journal_get_write_access()` /
+:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
+journalling layer to copy the unmodified
 data if it needs to. After all the buffer may be part of a previously
 uncommitted transaction. At this point you are at last ready to modify a
 buffer, and once you are have done so you need to call
-jbd2_journal_dirty_{meta,}data(). Or if you've asked for access to a
+:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
 buffer you now know is now longer required to be pushed back on the
-device you can call jbd2_journal_forget() in much the same way as you
-might have used bforget() in the past.
+device you can call :c:func:`jbd2_journal_forget` in much the same way as you
+might have used :c:func:`bforget` in the past.
 
-A jbd2_journal_flush() may be called at any time to commit and
+A :c:func:`jbd2_journal_flush` may be called at any time to commit and
 checkpoint all your transactions.
 
-Then at umount time , in your put_super() you can then call
-jbd2_journal_destroy() to clean up your in-core journal object.
+Then at umount time , in your :c:func:`put_super` you can then call
+:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
 
 Unfortunately there a couple of ways the journal layer can cause a
 deadlock. The first thing to note is that each task can only have a
 single outstanding transaction at any one time, remember nothing commits
-until the outermost jbd2_journal_stop(). This means you must complete
+until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
 the transaction at the end of each file/inode/address etc. operation you
 perform, so that the journalling system isn't re-entered on another
 journal. Since transactions can't be nested/batched across differing
 journals, and another filesystem other than yours (say ext4) may be
 modified in a later syscall.
 
-The second case to bear in mind is that jbd2_journal_start() can block
+The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
 if there isn't enough space in the journal for your transaction (based
 on the passed nblocks param) - when it blocks it merely(!) needs to wait
 for transactions to complete and be committed from other tasks, so
-essentially we are waiting for jbd2_journal_stop(). So to avoid
-deadlocks you must treat jbd2_journal_start/stop() as if they were
-semaphores and include them in your semaphore ordering rules to prevent
-deadlocks. Note that jbd2_journal_extend() has similar blocking
-behaviour to jbd2_journal_start() so you can deadlock here just as
-easily as on jbd2_journal_start().
+essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
+deadlocks you must treat :c:func:`jbd2_journal_start` /
+:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
+your semaphore ordering rules to prevent
+deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
+behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
+easily as on :c:func:`jbd2_journal_start`.
 
 Try to reserve the right number of blocks the first time. ;-). This will
 be the maximum number of blocks you are going to touch in this

@@ -222,13 +225,14 @@ With journal commit callbacks you can ask the journalling layer to call
 a callback function when the transaction is finally committed to disk,
 so that you can do some of your own management. You ask the journalling
 layer for calling the callback by simply setting
-journal->j_commit_callback function pointer and that function is
+``journal->j_commit_callback`` function pointer and that function is
 called after each transaction commit. You can also use
-transaction->t_private_list for attaching entries to a transaction
+``transaction->t_private_list`` for attaching entries to a transaction
 that need processing when the transaction commits.
 
 JBD2 also provides a way to block all transaction updates via
-jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a
+:c:func:`jbd2_journal_lock_updates()` /
+:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
 window with a clean and stable fs for a moment. E.g.
 
 ::

2.9.3
---
 include/linux/mutex.h  |  6 +++---
 kernel/futex.c         | 40 ++++++++++++++++++++--------------------
 kernel/locking/mutex.c |  6 +++---
 3 files changed, 26 insertions(+), 26 deletions(-)
index 1127fe31645d..ffcba1f337da 100644
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
  * raisins, and once those are gone this will be removed.
  *
  * Returns:
- *  MUTEX_TRYLOCK_FAILED    - trylock failed,
- *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
- *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ *  - MUTEX_TRYLOCK_FAILED    - trylock failed,
+ *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,
+ *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  */
 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
 mutex_trylock_recursive(struct mutex *lock)

index 357348a6cf6b..b8ae87d227da 100644
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
  *
  * Return: a negative error code or 0
  *
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
  *
  * For shared mappings, it's (page->index, file_inode(vma->vm_file),
  * offset_within_page).  For private mappings, it's (uaddr, current->mm).

@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
  * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
  *
  * Return:
- *  0 - ready to wait;
- *  1 - acquired the lock;
- * <0 - error
+ *  -  0 - ready to wait;
+ *  -  1 - acquired the lock;
+ *  - <0 - error
  *
  * The hb->lock and futex_key refs shall be held by the caller.
  */

@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
  * hb1 and hb2 must be held by the caller.
  *
  * Return:
- *  0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ *  -  0 - failed to acquire the lock atomically;
+ *  - >0 - acquired the lock, return value is vpid of the top_waiter
+ *  - <0 - error
  */
 static int futex_proxy_trylock_atomic(u32 __user *pifutex,
 				 struct futex_hash_bucket *hb1,

@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
  * uaddr2 atomically on behalf of the top waiter.
  *
  * Return:
- * >=0 - on success, the number of tasks requeued or woken;
- *  <0 - on error
+ *  - >=0 - on success, the number of tasks requeued or woken;
+ *  -  <0 - on error
  */
 static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
 			 u32 __user *uaddr2, int nr_wake, int nr_requeue,

@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
  * be paired with exactly one earlier call to queue_me().
  *
  * Return:
- *   1 - if the futex_q was still queued (and we removed unqueued it);
- *   0 - if the futex_q was already removed by the waking thread
+ *  - 1 - if the futex_q was still queued (and we removed unqueued it);
+ *  - 0 - if the futex_q was already removed by the waking thread
  */
 static int unqueue_me(struct futex_q *q)
 {

@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
  * acquire the lock. Must be called with the hb lock held.
  *
  * Return:
- *  1 - success, lock taken;
- *  0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ *  -  1 - success, lock taken;
+ *  -  0 - success, lock not taken;
+ *  - <0 - on error (-EFAULT)
  */
 static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
 {

@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
  * with no q.key reference on failure.
  *
  * Return:
- *  0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ *  -  0 - uaddr contains val and hb has been locked;
+ *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
  */
 static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
 			   struct futex_q *q, struct futex_hash_bucket **hb)

@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
  * called with the hb lock held.
  *
  * Return:
- *  0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ *  -  0 = no early wakeup detected;
+ *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR
  */
 static inline
 int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,

@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
  * If 4 or 7, we cleanup and return with -ETIMEDOUT.
  *
  * Return:
- *  0 - On success;
- * <0 - On error
+ *  -  0 - On success;
+ *  - <0 - On error
  */
 static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
 				 u32 val, ktime_t *abs_time, u32 bitset,

index 198527a62149..858a07590e39 100644
@@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
- *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * checks that will enforce the restrictions and will also do
+ * deadlock debugging)
  *
  * This function is similar to (but not equivalent to) down().
  */

2.9.3
---
 Documentation/DocBook/Makefile      |    2 +-
 Documentation/DocBook/libata.tmpl   | 1625 -----------------------------------
 Documentation/driver-api/index.rst  |    1 +
 Documentation/driver-api/libata.rst | 1027 ++++++++++++++++++++++
 4 files changed, 1029 insertions(+), 1626 deletions(-)
 delete mode 100644 Documentation/DocBook/libata.tmpl
 create mode 100644 Documentation/driver-api/libata.rst
index 2f767e30b59e..abe71345160b 100644
@@ -9,7 +9,7 @@
 DOCBOOKS := z8530book.xml  \
 	    networking.xml \
 	    lsm.xml \
-	    libata.xml mtdnand.xml librs.xml rapidio.xml \
+	    mtdnand.xml librs.xml rapidio.xml \
 	    s390-drivers.xml scsi.xml \
 	    sh.xml w1.xml
 

index 8058a87c1c74..c3c50b1bb96c 100644
@@ -32,6 +32,7 @@ available subsections can be seen below.
    i2c
    hsi
    edac
+   libata
    miscellaneous
    vme
    80211/index

2.9.3
---
 Documentation/driver-api/mtdnand.rst | 24 +++++++-----------------
 1 file changed, 7 insertions(+), 17 deletions(-)
index 8723175f955e..7c19795ebb4a 100644
@@ -843,10 +843,8 @@ Chip option constants
 Constants for chip id table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the chip functionality::
 
     /* Buswitdh is 16 bit */
     #define NAND_BUSWIDTH_16    0x00000002

@@ -867,10 +865,8 @@ describe the chip functionality.
 Constants for runtime options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the functionality::
 
     /* The hw ecc generator provides a syndrome instead a ecc value on read
      * This can only work if we have the ecc bytes directly behind the

@@ -881,9 +877,7 @@ describe the functionality.
 ECC selection constants
 -----------------------
 
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
 
     /* No ECC. Usage is not recommended ! */
     #define NAND_ECC_NONE       0

@@ -903,9 +897,7 @@ Hardware control related constants
 ----------------------------------
 
 These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
 
     /* Select the chip by setting nCE to low */
     #define NAND_CTL_SETNCE     1

@@ -929,9 +921,7 @@ Bad block table related constants
 ---------------------------------
 
 These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
 
     /* Options for the bad block table descriptors */
 

2.9.3
---
 Documentation/DocBook/w1.tmpl      | 101 -------------------------------------
 Documentation/driver-api/index.rst |   1 +
 Documentation/driver-api/w1.rst    |  70 +++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 101 deletions(-)
 delete mode 100644 Documentation/DocBook/w1.tmpl
 create mode 100644 Documentation/driver-api/w1.rst
deleted file mode 100644
index b0228d4c81bb..000000000000
@@ -1,101 +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="w1id">
-  <bookinfo>
-    <title>W1: Dallas' 1-wire bus</title>
-
-    <authorgroup>
-      <author>
-        <firstname>David</firstname>
-        <surname>Fries</surname>
-        <affiliation>
-          <address>
-            <email>[email protected]</email>
-          </address>
-        </affiliation>
-      </author>
-
-    </authorgroup>
-
-    <copyright>
-      <year>2013</year>
-      <!--
-      <holder></holder>
-      -->
-    </copyright>
-
-    <legalnotice>
-      <para>
-        This documentation is free software; you can redistribute
-        it and/or modify it under the terms of the GNU General Public
-        License version 2.
-      </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.
-        For more details see the file COPYING in the source
-        distribution of Linux.
-      </para>
-    </legalnotice>
-  </bookinfo>
-
-  <toc></toc>
-
-  <chapter id="w1_internal">
-    <title>W1 API internal to the kernel</title>
-
-    <sect1 id="w1_internal_api">
-      <title>W1 API internal to the kernel</title>
-      <sect2 id="w1.h">
-        <title>drivers/w1/w1.h</title>
-        <para>W1 core functions.</para>
-!Idrivers/w1/w1.h
-      </sect2>
-
-      <sect2 id="w1.c">
-        <title>drivers/w1/w1.c</title>
-        <para>W1 core functions.</para>
-!Idrivers/w1/w1.c
-      </sect2>
-
-      <sect2 id="w1_family.h">
-        <title>drivers/w1/w1_family.h</title>
-        <para>Allows registering device family operations.</para>
-!Idrivers/w1/w1_family.h
-      </sect2>
-
-      <sect2 id="w1_family.c">
-        <title>drivers/w1/w1_family.c</title>
-        <para>Allows registering device family operations.</para>
-!Edrivers/w1/w1_family.c
-      </sect2>
-
-      <sect2 id="w1_int.c">
-        <title>drivers/w1/w1_int.c</title>
-        <para>W1 internal initialization for master devices.</para>
-!Edrivers/w1/w1_int.c
-      </sect2>
-
-      <sect2 id="w1_netlink.h">
-        <title>drivers/w1/w1_netlink.h</title>
-        <para>W1 external netlink API structures and commands.</para>
-!Idrivers/w1/w1_netlink.h
-      </sect2>
-
-      <sect2 id="w1_io.c">
-        <title>drivers/w1/w1_io.c</title>
-        <para>W1 input/output.</para>
-!Edrivers/w1/w1_io.c
-!Idrivers/w1/w1_io.c
-      </sect2>
-
-    </sect1>
-
-
-  </chapter>
-
-</book>

index 9589b06e374e..8610aab8f342 100644
@@ -35,6 +35,7 @@ available subsections can be seen below.
    scsi
    libata
    miscellaneous
+   w1
    s390-drivers
    vme
    80211/index

2.9.3
---
 Documentation/DocBook/Makefile            |    1 -
 Documentation/DocBook/kernel-locking.tmpl | 2151 -----------------------------
 Documentation/kernel-hacking/index.rst    |    1 +
 Documentation/kernel-hacking/locking.rst  | 1453 +++++++++++++++++++
 4 files changed, 1454 insertions(+), 2152 deletions(-)
 delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
 create mode 100644 Documentation/kernel-hacking/locking.rst
index 7d7482b5ad92..9df94f7c2003 100644
@@ -7,7 +7,6 @@
 # list of DOCBOOKS.
 
 DOCBOOKS := z8530book.xml  \
-	    kernel-locking.xml \
 	    networking.xml \
 	    filesystems.xml lsm.xml kgdb.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \

index ba208bf03ce9..fcb0eda3cca3 100644
@@ -6,3 +6,4 @@ Kernel Hacking Guides
    :maxdepth: 2
 
    hacking
+   locking

2.9.3
---
 Documentation/conf.py | 2 ++
 1 file changed, 2 insertions(+)
index bca751960dec..2e215477edf5 100644
@@ -373,6 +373,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
      'The kernel development community', 'manual'),
+    ('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
+     'The kernel development community', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

2.9.3
---
 Documentation/DocBook/Makefile       |   4 +-
 Documentation/DocBook/rapidio.tmpl   | 155 -----------------------------------
 Documentation/driver-api/index.rst   |   1 +
 Documentation/driver-api/rapidio.rst | 107 ++++++++++++++++++++++++
 4 files changed, 110 insertions(+), 157 deletions(-)
 delete mode 100644 Documentation/DocBook/rapidio.tmpl
 create mode 100644 Documentation/driver-api/rapidio.rst
index 3bbda02d6aee..baedb14f3b40 100644
@@ -8,8 +8,8 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml librs.xml rapidio.xml \
-	    sh.xml w1.xml
+	    mtdnand.xml librs.xml \
+	    sh.xml
 
 ifeq ($(DOCBOOKS),)
 

index 8610aab8f342..1f8517db39c7 100644
@@ -36,6 +36,7 @@ available subsections can be seen below.
    libata
    miscellaneous
    w1
+   rapidio
    s390-drivers
    vme
    80211/index

2.9.3
---
 Documentation/conf.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)
index 0ce8001a50b6..1774357150a3 100644
@@ -281,6 +281,7 @@ latex_elements = {
 	\\definecolor{NoteColor}{RGB}{204,255,255}
 	\\definecolor{WarningColor}{RGB}{255,204,204}
 	\\definecolor{AttentionColor}{RGB}{255,255,204}
+	\\definecolor{ImportantColor}{RGB}{192,255,204}
 	\\definecolor{OtherColor}{RGB}{204,204,204}
         \\newlength{\\mynoticelength}
         \\makeatletter\\newenvironment{coloredbox}[1]{%

@@ -301,7 +302,12 @@ latex_elements = {
 	            \\ifthenelse%
 	            {\\equal{\\py@noticetype}{attention}}%
 	            {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
-	            {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+		    {%
+	               \\ifthenelse%
+	               {\\equal{\\py@noticetype}{important}}%
+	               {\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
+	               {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+		    }%
 		 }%
 	      }%
         }\\makeatother

2.9.3
---
 Documentation/filesystems/index.rst | 1 -
 1 file changed, 1 deletion(-)
index 148becd91cba..256e10eedba4 100644
@@ -287,7 +287,6 @@ Transasction Level
 ~~~~~~~~~~~~~~~~~~
 
 .. kernel-doc:: fs/jbd2/transaction.c
-   :export:
 
 See also
 --------

2.9.3
---
 Documentation/kernel-hacking/locking.rst | 37 ++++++++++++--------------------
 1 file changed, 14 insertions(+), 23 deletions(-)
index 976b2703df75..17774b1f7587 100644
@@ -319,29 +319,20 @@ Remember the advice above: you can always use
 :c:func:`spin_lock_irqsave()`, which is a superset of all other
 spinlock primitives.
 
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-|                  | IRQ Handler A   | IRQ Handler B   | Softirq A   | Softirq B   | Tasklet A   | Tasklet B   | Timer A   | Timer B   | User Context A   | User Context B   |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| IRQ Handler A    | None            |                 |             |             |             |             |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| IRQ Handler B    | SLIS            | None            |             |             |             |             |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Softirq A        | SLI             | SLI             | SL          |             |             |             |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Softirq B        | SLI             | SLI             | SL          | SL          |             |             |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Tasklet A        | SLI             | SLI             | SL          | SL          | None        |             |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Tasklet B        | SLI             | SLI             | SL          | SL          | SL          | None        |           |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Timer A          | SLI             | SLI             | SL          | SL          | SL          | SL          | None      |           |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| Timer B          | SLI             | SLI             | SL          | SL          | SL          | SL          | SL        | None      |                  |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| User Context A   | SLI             | SLI             | SLBH        | SLBH        | SLBH        | SLBH        | SLBH      | SLBH      | None             |                  |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
-| User Context B   | SLI             | SLI             | SLBH        | SLBH        | SLBH        | SLBH        | SLBH      | SLBH      | MLI              | None             |
-+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+
+============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
+.              IRQ Handler A IRQ Handler B Softirq A Softirq B Tasklet A Tasklet B Timer A Timer B User Context A User Context B
+============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
+IRQ Handler A  None
+IRQ Handler B  SLIS          None
+Softirq A      SLI           SLI           SL
+Softirq B      SLI           SLI           SL        SL
+Tasklet A      SLI           SLI           SL        SL        None
+Tasklet B      SLI           SLI           SL        SL        SL        None
+Timer A        SLI           SLI           SL        SL        SL        SL        None
+Timer B        SLI           SLI           SL        SL        SL        SL        SL      None
+User Context A SLI           SLI           SLBH      SLBH      SLBH      SLBH      SLBH    SLBH    None
+User Context B SLI           SLI           SLBH      SLBH      SLBH      SLBH      SLBH    SLBH    MLI            None
+============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
 
 Table: Table of Locking Requirements
 

2.9.3
---
 Documentation/DocBook/Makefile        |   1 -
 Documentation/DocBook/networking.tmpl | 111 -------------------------
 Documentation/conf.py                 |   2 +
 Documentation/index.rst               |   1 +
 Documentation/networking/conf.py      |  10 +++
 Documentation/networking/index.rst    |  17 ++++
 Documentation/networking/kapi.rst     | 147 ++++++++++++++++++++++++++++++++++
 7 files changed, 177 insertions(+), 112 deletions(-)
 delete mode 100644 Documentation/DocBook/networking.tmpl
 create mode 100644 Documentation/networking/conf.py
 create mode 100644 Documentation/networking/index.rst
 create mode 100644 Documentation/networking/kapi.rst
index a25bf10384e1..8a90891c3712 100644
@@ -7,7 +7,6 @@
 # list of DOCBOOKS.
 
 DOCBOOKS := z8530book.xml  \
-	    networking.xml \
 	    lsm.xml \
 	    mtdnand.xml librs.xml rapidio.xml \
 	    scsi.xml \

index ad9a4781b330..dfe14f7525d0 100644
@@ -369,6 +369,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
      'The kernel development community', 'manual'),
+    ('networking/index', 'networking.tex', 'Linux Networking Documentation',
+     'The kernel development community', 'manual'),
     ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
      'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',

index dae365f3820e..25c4da41da6b 100644
@@ -68,6 +68,7 @@ needed).
    driver-api/index
    core-api/index
    media/index
+   networking/index
    input/index
    gpu/index
    security/index

new file mode 100644
index 000000000000..40f69e67a883
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Networking Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'networking.tex', project,
+     'The kernel development community', 'manual'),
+]

new file mode 100644
index 000000000000..ff652ff279e8
@@ -0,0 +1,17 @@
+Linux Networking Documentation
+==============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   kapi
+
+.. only::  subproject
+
+   Indices
+   =======
+
+   * :ref:`genindex`
+

2.9.3
---
 kernel/irq/chip.c    | 2 +-
 kernel/irq/handle.c  | 2 +-
 kernel/irq/irqdesc.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
index 686be4b73018..4188a0a7691f 100644
@@ -7,7 +7,7 @@
  * This file contains the core interrupt handling code, for irq-chip
  * based architectures.
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  */
 
 #include <linux/irq.h>

index d3f24905852c..bbf9a7174283 100644
@@ -6,7 +6,7 @@
  *
  * This file contains the core interrupt handling code.
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  *
  */
 

index 00bb0aeea1d0..22e443133987 100644
@@ -4,7 +4,7 @@
  *
  * This file contains the interrupt descriptor management code
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  *
  */
 #include <linux/irq.h>

2.9.3
---
 include/linux/skbuff.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
index a098d95b3d84..25b1659c832a 100644
@@ -2691,7 +2691,7 @@ bool skb_page_frag_refill(unsigned int sz, struct page_frag *pfrag, gfp_t prio);
  * @offset: the offset within the fragment (starting at the
  *          fragment's own offset)
  * @size: the number of bytes to map
- * @dir: the direction of the mapping (%PCI_DMA_*)
+ * @dir: the direction of the mapping (``PCI_DMA_*``)
  *
  * Maps the page associated with @frag to @device.
  */

2.9.3
---
 MAINTAINERS | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
index f42daf74f541..8609dba03cbc 100644
@@ -3567,7 +3567,6 @@ T:	git git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6.git
 S:	Maintained
 F:	Documentation/crypto/
 F:	Documentation/devicetree/bindings/crypto/
-F:	Documentation/DocBook/crypto-API.tmpl
 F:	arch/*/crypto/
 F:	crypto/
 F:	drivers/crypto/

@@ -7364,7 +7363,7 @@ W:	http://kgdb.wiki.kernel.org/
 L:	[email protected]
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git
 S:	Maintained
-F:	Documentation/DocBook/kgdb.tmpl
+F:	Documentation/dev-tools/kgdb.rst
 F:	drivers/misc/kgdbts.c
 F:	drivers/tty/serial/kgdboc.c
 F:	include/linux/kdb.h

@@ -10971,7 +10970,7 @@ S:	Supported
 F:	arch/s390/
 F:	drivers/s390/
 F:	Documentation/s390/
-F:	Documentation/DocBook/s390*
+F:	Documentation/driver-api/s390-drivers.rst
 
 S390 COMMON I/O LAYER
 M:	Sebastian Ott <[email protected]>

2.9.3
---
 Documentation/DocBook/Makefile   |   2 +-
 Documentation/DocBook/librs.tmpl | 289 ---------------------------------------
 Documentation/core-api/index.rst |   1 +
 Documentation/core-api/librs.rst | 212 ++++++++++++++++++++++++++++
 4 files changed, 214 insertions(+), 290 deletions(-)
 delete mode 100644 Documentation/DocBook/librs.tmpl
 create mode 100644 Documentation/core-api/librs.rst
index baedb14f3b40..0a82f6253682 100644
@@ -8,7 +8,7 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml librs.xml \
+	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

index 62abd36bfffb..0606be3a3111 100644
@@ -19,6 +19,7 @@ Core utilities
    workqueue
    genericirq
    flexible-arrays
+   librs
 
 Interfaces for kernel debugging
 ===============================

2.9.3
---
 Documentation/conf.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
index 1bad6a4d6348..15f34d6863a7 100644
@@ -359,9 +359,7 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
      'The kernel development community', 'manual'),
-    ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
-     'The kernel development community', 'manual'),
-    ('kernel-hacking/index', 'kernel-hacking.tex', 'Kernel Hacking Guides',
+    ('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To Hacking The Linux Kernel',
      'The kernel development community', 'manual'),
     ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
      'The kernel development community', 'manual'),

2.9.3
---
 Documentation/DocBook/Makefile            |    2 +-
 Documentation/DocBook/kernel-hacking.tmpl | 1312 -----------------------------
 Documentation/conf.py                     |    2 +
 Documentation/index.rst                   |    1 +
 Documentation/kernel-hacking/conf.py      |   10 +
 Documentation/kernel-hacking/hacking.rst  |  794 +++++++++++++++++
 Documentation/kernel-hacking/index.rst    |    8 +
 7 files changed, 816 insertions(+), 1313 deletions(-)
 delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl
 create mode 100644 Documentation/kernel-hacking/conf.py
 create mode 100644 Documentation/kernel-hacking/hacking.rst
 create mode 100644 Documentation/kernel-hacking/index.rst
index 85916f13d330..7d7482b5ad92 100644
@@ -7,7 +7,7 @@
 # list of DOCBOOKS.
 
 DOCBOOKS := z8530book.xml  \
-	    kernel-hacking.xml kernel-locking.xml \
+	    kernel-locking.xml \
 	    networking.xml \
 	    filesystems.xml lsm.xml kgdb.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \

index bacf9d337c89..0ce8001a50b6 100644
@@ -352,6 +352,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
      'The kernel development community', 'manual'),
+    ('kernel-hacking/index', 'kernel-hacking.tex', 'Kernel Hacking Guides',
+     'The kernel development community', 'manual'),
     ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
      'The kernel development community', 'manual'),
     ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',

index bc67dbf76eb0..01a24486ea5f 100644
@@ -51,6 +51,7 @@ merged much easier.
    process/index
    dev-tools/index
    doc-guide/index
+   kernel-hacking/index
 
 Kernel API documentation
 ------------------------

new file mode 100644
index 000000000000..3d8acf0f33ad
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Kernel Hacking Guides"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'kernel-hacking.tex', project,
+     'The kernel development community', 'manual'),
+]

new file mode 100644
index 000000000000..ba208bf03ce9
@@ -0,0 +1,8 @@
+=====================
+Kernel Hacking Guides
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   hacking

2.9.3
---
 Documentation/DocBook/Makefile       |    1 -
 Documentation/DocBook/mtdnand.tmpl   | 1291 ----------------------------------
 Documentation/driver-api/index.rst   |    1 +
 Documentation/driver-api/mtdnand.rst | 1020 +++++++++++++++++++++++++++
 4 files changed, 1021 insertions(+), 1292 deletions(-)
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 create mode 100644 Documentation/driver-api/mtdnand.rst
index 0a82f6253682..226e5e9fc801 100644
@@ -8,7 +8,6 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

index 1f8517db39c7..3cf1acebc4ee 100644
@@ -34,6 +34,7 @@ available subsections can be seen below.
    edac
    scsi
    libata
+   mtdnand
    miscellaneous
    w1
    rapidio

2.9.3
---
 fs/debugfs/file.c       | 2 +-
 include/linux/debugfs.h | 2 +-
 lib/Kconfig.debug       | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
index 354e2ab62031..6dabc4a10396 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/filesystems for more details.
+ *  See Documentation/filesystems/ for more details.
  *
  */
 

index 9174b0d28582..aa86e6d8c1aa 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/filesystems for more details.
+ *  See Documentation/filesystems/ for more details.
  */
 
 #ifndef _DEBUGFS_H_

index e4587ebe52c7..b7882d45f48e 100644
@@ -286,7 +286,7 @@ config DEBUG_FS
 	  write to these files.
 
 	  For detailed documentation on the debugfs API, see
-	  Documentation/DocBook/filesystems.
+	  Documentation/filesystems/.
 
 	  If unsure, say N.
 

2.9.3
---
 Documentation/driver-api/libata.rst | 244 ++++++++++++++++++------------------
 1 file changed, 124 insertions(+), 120 deletions(-)
index 774bf238ff79..4adc056f7635 100644
@@ -18,18 +18,19 @@ internals, and a couple sample ATA low-level drivers.
 libata Driver API
 =================
 
-struct ata_port_operations is defined for every low-level libata
+:c:type:`struct ata_port_operations <ata_port_operations>`
+is defined for every low-level libata
 hardware driver, and it controls how the low-level driver interfaces
 with the ATA and SCSI layers.
 
-FIS-based drivers will hook into the system with ->qc_prep() and
-->qc_issue() high-level hooks. Hardware which behaves in a manner
+FIS-based drivers will hook into the system with ``->qc_prep()`` and
+``->qc_issue()`` high-level hooks. Hardware which behaves in a manner
 similar to PCI IDE hardware may utilize several generic helpers,
 defining at a bare minimum the bus I/O addresses of the ATA shadow
 register blocks.
 
-struct ata_port_operations
-----------------------------
+:c:type:`struct ata_port_operations <ata_port_operations>`
+----------------------------------------------------------
 
 Disable ATA port
 ~~~~~~~~~~~~~~~~

@@ -39,13 +40,13 @@ Disable ATA port
     void (*port_disable) (struct ata_port *);
 
 
-Called from ata_bus_probe() error path, as well as when unregistering
+Called from :c:func:`ata_bus_probe` error path, as well as when unregistering
 from the SCSI module (rmmod, hot unplug). This function should do
 whatever needs to be done to take the port out of use. In most cases,
-ata_port_disable() can be used as this hook.
+:c:func:`ata_port_disable` can be used as this hook.
 
-Called from ata_bus_probe() on a failed probe. Called from
-ata_scsi_release().
+Called from :c:func:`ata_bus_probe` on a failed probe. Called from
+:c:func:`ata_scsi_release`.
 
 Post-IDENTIFY device configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -73,22 +74,22 @@ Set PIO/DMA mode
 
 
 Hooks called prior to the issue of SET FEATURES - XFER MODE command. The
-optional ->mode_filter() hook is called when libata has built a mask of
-the possible modes. This is passed to the ->mode_filter() function
+optional ``->mode_filter()`` hook is called when libata has built a mask of
+the possible modes. This is passed to the ``->mode_filter()`` function
 which should return a mask of valid modes after filtering those
 unsuitable due to hardware limits. It is not valid to use this interface
 to add modes.
 
-dev->pio_mode and dev->dma_mode are guaranteed to be valid when
-->set_piomode() and when ->set_dmamode() is called. The timings for
+``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when
+``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for
 any other drive sharing the cable will also be valid at this point. That
 is the library records the decisions for the modes of each drive on a
 channel before it attempts to set any of them.
 
-->post_set_mode() is called unconditionally, after the SET FEATURES -
+``->post_set_mode()`` is called unconditionally, after the SET FEATURES -
 XFER MODE command completes successfully.
 
-->set_piomode() is always called (if present), but ->set_dma_mode()
+``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``
 is only called if DMA is possible.
 
 Taskfile read/write

@@ -100,11 +101,11 @@ Taskfile read/write
     void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
 
 
-->tf_load() is called to load the given taskfile into hardware
-registers / DMA buffers. ->tf_read() is called to read the hardware
+``->tf_load()`` is called to load the given taskfile into hardware
+registers / DMA buffers. ``->tf_read()`` is called to read the hardware
 registers / DMA buffers, to obtain the current set of taskfile register
 values. Most drivers for taskfile-based hardware (PIO or MMIO) use
-ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
+:c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks.
 
 PIO data read/write
 ~~~~~~~~~~~~~~~~~~~

@@ -117,8 +118,8 @@ PIO data read/write
 All bmdma-style drivers must implement this hook. This is the low-level
 operation that actually copies the data bytes during a PIO data
 transfer. Typically the driver will choose one of
-ata_sff_data_xfer_noirq(), ata_sff_data_xfer(), or
-ata_sff_data_xfer32().
+:c:func:`ata_sff_data_xfer_noirq`, :c:func:`ata_sff_data_xfer`, or
+:c:func:`ata_sff_data_xfer32`.
 
 ATA command execute
 ~~~~~~~~~~~~~~~~~~~

@@ -128,9 +129,9 @@ ATA command execute
     void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
 
 
-causes an ATA command, previously loaded with ->tf_load(), to be
+causes an ATA command, previously loaded with ``->tf_load()``, to be
 initiated in hardware. Most drivers for taskfile-based hardware use
-ata_sff_exec_command() for this hook.
+:c:func:`ata_sff_exec_command` for this hook.
 
 Per-cmd ATAPI DMA capabilities filter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -159,7 +160,7 @@ Read specific ATA shadow registers
 Reads the Status/AltStatus ATA shadow register from hardware. On some
 hardware, reading the Status register has the side effect of clearing
 the interrupt condition. Most drivers for taskfile-based hardware use
-ata_sff_check_status() for this hook.
+:c:func:`ata_sff_check_status` for this hook.
 
 Write specific ATA shadow register
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -184,7 +185,7 @@ Issues the low-level hardware command(s) that causes one of N hardware
 devices to be considered 'selected' (active and available for use) on
 the ATA bus. This generally has no meaning on FIS-based devices.
 
-Most drivers for taskfile-based hardware use ata_sff_dev_select() for
+Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
 this hook.
 
 Private tuning method

@@ -222,28 +223,28 @@ Control PCI IDE BMDMA engine
 
 
 When setting up an IDE BMDMA transaction, these hooks arm
-(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the
-hardware's DMA engine. ->bmdma_status is used to read the standard PCI
+(``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the
+hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
 IDE DMA Status register.
 
 These hooks are typically either no-ops, or simply not implemented, in
 FIS-based drivers.
 
-Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
-hook. ata_bmdma_setup() will write the pointer to the PRD table to the
-IDE PRD Table Address register, enable DMA in the DMA Command register,
-and call exec_command() to begin the transfer.
+Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the
+:c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer
+to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA
+Command register, and call :c:func:`exec_command` to begin the transfer.
 
-Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
-hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
-Command register.
+Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the
+:c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the
+ATA_DMA_START flag to the DMA Command register.
 
-Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
-hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
-command register.
+Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the
+:c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START
+flag in the DMA command register.
 
-Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status()
-hook.
+Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the
+:c:func:`bmdma_status` hook.
 
 High-level taskfile hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -255,19 +256,19 @@ High-level taskfile hooks
 
 
 Higher-level hooks, these two hooks can potentially supercede several of
-the above taskfile/DMA engine hooks. ->qc_prep is called after the
+the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
 buffers have been DMA-mapped, and is typically used to populate the
 hardware's DMA scatter-gather table. Most drivers use the standard
-ata_qc_prep() helper function, but more advanced drivers roll their
+:c:func:`ata_qc_prep` helper function, but more advanced drivers roll their
 own.
 
-->qc_issue is used to make a command active, once the hardware and S/G
+``->qc_issue`` is used to make a command active, once the hardware and S/G
 tables have been prepared. IDE BMDMA drivers use the helper function
-ata_qc_issue_prot() for taskfile protocol-based dispatch. More
-advanced drivers implement their own ->qc_issue.
+:c:func:`ata_qc_issue_prot` for taskfile protocol-based dispatch. More
+advanced drivers implement their own ``->qc_issue``.
 
-ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
-->bmdma_start() as necessary to initiate a transfer.
+:c:func:`ata_qc_issue_prot` calls ``->tf_load()``, ``->bmdma_setup()``, and
+``->bmdma_start()`` as necessary to initiate a transfer.
 
 Exception and probe handling (EH)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -278,7 +279,7 @@ Exception and probe handling (EH)
     void (*phy_reset) (struct ata_port *ap);
 
 
-Deprecated. Use ->error_handler() instead.
+Deprecated. Use ``->error_handler()`` instead.
 
 ::
 

@@ -286,18 +287,18 @@ Deprecated. Use ->error_handler() instead.
     void (*thaw) (struct ata_port *ap);
 
 
-ata_port_freeze() is called when HSM violations or some other
+:c:func:`ata_port_freeze` is called when HSM violations or some other
 condition disrupts normal operation of the port. A frozen port is not
 allowed to perform any operation until the port is thawed, which usually
 follows a successful reset.
 
-The optional ->freeze() callback can be used for freezing the port
+The optional ``->freeze()`` callback can be used for freezing the port
 hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
 cannot be frozen hardware-wise, the interrupt handler must ack and clear
 interrupts unconditionally while the port is frozen.
 
-The optional ->thaw() callback is called to perform the opposite of
-->freeze(): prepare the port for normal operation once again. Unmask
+The optional ``->thaw()`` callback is called to perform the opposite of
+``->freeze()``: prepare the port for normal operation once again. Unmask
 interrupts, start DMA engine, etc.
 
 ::

@@ -305,10 +306,10 @@ interrupts, start DMA engine, etc.
     void (*error_handler) (struct ata_port *ap);
 
 
-->error_handler() is a driver's hook into probe, hotplug, and recovery
+``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
 and other exceptional conditions. The primary responsibility of an
-implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with
-a set of EH hooks as arguments:
+implementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh`
+with a set of EH hooks as arguments:
 
 'prereset' hook (may be NULL) is called during an EH reset, before any
 other actions are taken.

@@ -327,7 +328,7 @@ called to perform the low-level EH reset.
 
 Perform any hardware-specific actions necessary to finish processing
 after executing a probe-time or EH-time command via
-ata_exec_internal().
+:c:func:`ata_exec_internal`.
 
 Hardware interrupt handling
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -338,20 +339,20 @@ Hardware interrupt handling
     void (*irq_clear) (struct ata_port *);
 
 
-->irq_handler is the interrupt handling routine registered with the
-system, by libata. ->irq_clear is called during probe just before the
+``->irq_handler`` is the interrupt handling routine registered with the
+system, by libata. ``->irq_clear`` is called during probe just before the
 interrupt handler is registered, to be sure hardware is quiet.
 
 The second argument, dev_instance, should be cast to a pointer to
-struct ata_host_set.
+:c:type:`struct ata_host_set <ata_host_set>`.
 
-Most legacy IDE drivers use ata_sff_interrupt() for the irq_handler
+Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler
 hook, which scans all ports in the host_set, determines which queued
 command was active (if any), and calls ata_sff_host_intr(ap,qc).
 
-Most legacy IDE drivers use ata_sff_irq_clear() for the irq_clear()
-hook, which simply clears the interrupt and error flags in the DMA
-status register.
+Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the
+:c:func:`irq_clear` hook, which simply clears the interrupt and error flags
+in the DMA status register.
 
 SATA phy read/write
 ~~~~~~~~~~~~~~~~~~~

@@ -365,8 +366,8 @@ SATA phy read/write
 
 
 Read and write standard SATA phy registers. Currently only used if
-->phy_reset hook called the sata_phy_reset() helper function. sc_reg
-is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
+``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function.
+sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
 
 Init and shutdown
 ~~~~~~~~~~~~~~~~~

@@ -378,21 +379,21 @@ Init and shutdown
     void (*host_stop) (struct ata_host_set *host_set);
 
 
-->port_start() is called just after the data structures for each port
+``->port_start()`` is called just after the data structures for each port
 are initialized. Typically this is used to alloc per-port DMA buffers /
 tables / rings, enable DMA engines, and similar tasks. Some drivers also
 use this entry point as a chance to allocate driver-private memory for
-ap->private_data.
+``ap->private_data``.
 
-Many drivers use ata_port_start() as this hook or call it from their
-own port_start() hooks. ata_port_start() allocates space for a legacy
-IDE PRD table and returns.
+Many drivers use :c:func:`ata_port_start` as this hook or call it from their
+own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for
+a legacy IDE PRD table and returns.
 
-->port_stop() is called after ->host_stop(). Its sole function is to
+``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
 release DMA/memory resources, now that they are no longer actively being
 used. Many drivers also free driver-private data from port at this time.
 
-->host_stop() is called after all ->port_stop() calls have completed.
+``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
 The hook must finalize hardware shutdown, release DMA and other
 resources, etc. This hook may be specified as NULL, in which case it is
 not called.

@@ -407,7 +408,8 @@ exceptions doc first.
 Origins of commands
 -------------------
 
-In libata, a command is represented with struct ata_queued_cmd or qc.
+In libata, a command is represented with
+:c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc.
 qc's are preallocated during port initialization and repetitively used
 for command executions. Currently only one qc is allocated per port but
 yet-to-be-merged NCQ branch allocates one for each tag and maps each qc

@@ -423,17 +425,17 @@ How commands are issued
 -----------------------
 
 Internal commands
-    First, qc is allocated and initialized using ata_qc_new_init().
-    Although ata_qc_new_init() doesn't implement any wait or retry
+    First, qc is allocated and initialized using :c:func:`ata_qc_new_init`.
+    Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry
     mechanism when qc is not available, internal commands are currently
     issued only during initialization and error recovery, so no other
     command is active and allocation is guaranteed to succeed.
 
     Once allocated qc's taskfile is initialized for the command to be
     executed. qc currently has two mechanisms to notify completion. One
-    is via qc->complete_fn() callback and the other is completion
-    qc->waiting. qc->complete_fn() callback is the asynchronous path
-    used by normal SCSI translated commands and qc->waiting is the
+    is via ``qc->complete_fn()`` callback and the other is completion
+    ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
+    used by normal SCSI translated commands and ``qc->waiting`` is the
     synchronous (issuer sleeps in process context) path used by internal
     commands.
 

@@ -441,21 +443,21 @@ Internal commands
     qc is issued.
 
 SCSI commands
-    All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand
-    callback. scmds can either be simulated or translated. No qc is
-    involved in processing a simulated scmd. The result is computed
-    right away and the scmd is completed.
+    All libata drivers use :c:func:`ata_scsi_queuecmd` as
+    ``hostt->queuecommand`` callback. scmds can either be simulated or
+    translated. No qc is involved in processing a simulated scmd. The
+    result is computed right away and the scmd is completed.
 
-    For a translated scmd, ata_qc_new_init() is invoked to allocate a
+    For a translated scmd, :c:func:`ata_qc_new_init` is invoked to allocate a
     qc and the scmd is translated into the qc. SCSI midlayer's
     completion notification function pointer is stored into
-    qc->scsidone.
+    ``qc->scsidone``.
 
-    qc->complete_fn() callback is used for completion notification. ATA
-    commands use ata_scsi_qc_complete() while ATAPI commands use
-    atapi_qc_complete(). Both functions end up calling qc->scsidone to
-    notify upper layer when the qc is finished. After translation is
-    completed, the qc is issued with ata_qc_issue().
+    ``qc->complete_fn()`` callback is used for completion notification. ATA
+    commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use
+    :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
+    to notify upper layer when the qc is finished. After translation is
+    completed, the qc is issued with :c:func:`ata_qc_issue`.
 
     Note that SCSI midlayer invokes hostt->queuecommand while holding
     host_set lock, so all above occur while holding host_set lock.

@@ -495,34 +497,34 @@ ATAPI PIO
 How commands are completed
 --------------------------
 
-Once issued, all qc's are either completed with ata_qc_complete() or
+Once issued, all qc's are either completed with :c:func:`ata_qc_complete` or
 time out. For commands which are handled by interrupts,
-ata_host_intr() invokes ata_qc_complete(), and, for PIO tasks,
-pio_task invokes ata_qc_complete(). In error cases, packet_task may
+:c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks,
+pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may
 also complete commands.
 
-ata_qc_complete() does the following.
+:c:func:`ata_qc_complete` does the following.
 
 1. DMA memory is unmapped.
 
 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
 
-3. qc->complete_fn() callback is invoked. If the return value of the
+3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the
    callback is not zero. Completion is short circuited and
-   ata_qc_complete() returns.
+   :c:func:`ata_qc_complete` returns.
 
-4. __ata_qc_complete() is called, which does
+4. :c:func:`__ata_qc_complete` is called, which does
 
-   1. qc->flags is cleared to zero.
+   1. ``qc->flags`` is cleared to zero.
 
-   2. ap->active_tag and qc->tag are poisoned.
+   2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
 
-   3. qc->waiting is cleared & completed (in that order).
+   3. ``qc->waiting`` is cleared & completed (in that order).
 
-   4. qc is deallocated by clearing appropriate bit in ap->qactive.
+   4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
 
 So, it basically notifies upper layer and deallocates qc. One exception
-is short-circuit path in #3 which is used by atapi_qc_complete().
+is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
 
 For all non-ATAPI commands, whether it fails or not, almost the same
 code path is taken and very little error handling takes place. A qc is

@@ -531,33 +533,33 @@ otherwise.
 
 However, failed ATAPI commands require more handling as REQUEST SENSE is
 needed to acquire sense data. If an ATAPI command fails,
-ata_qc_complete() is invoked with error status, which in turn invokes
-atapi_qc_complete() via qc->complete_fn() callback.
+:c:func:`ata_qc_complete` is invoked with error status, which in turn invokes
+:c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
 
-This makes atapi_qc_complete() set scmd->result to
+This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
 SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the
-sense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer
-will invoke EH for the scmd, and returning 1 makes ata_qc_complete()
+sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
+will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`
 to return without deallocating the qc. This leads us to
-ata_scsi_error() with partially completed qc.
+:c:func:`ata_scsi_error` with partially completed qc.
 
-ata_scsi_error()
-------------------
+:c:func:`ata_scsi_error`
+------------------------
 
-ata_scsi_error() is the current transportt->eh_strategy_handler()
+:c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
 for libata. As discussed above, this will be entered in two cases -
 timeout and ATAPI error completion. This function calls low level libata
-driver's eng_timeout() callback, the standard callback for which is
-ata_eng_timeout(). It checks if a qc is active and calls
-ata_qc_timeout() on the qc if so. Actual error handling occurs in
-ata_qc_timeout().
+driver's :c:func:`eng_timeout` callback, the standard callback for which is
+:c:func:`ata_eng_timeout`. It checks if a qc is active and calls
+:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in
+:c:func:`ata_qc_timeout`.
 
-If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
+If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and
 completes the qc. Note that as we're currently in EH, we cannot call
 scsi_done. As described in SCSI EH doc, a recovered scmd should be
-either retried with scsi_queue_insert() or finished with
-scsi_finish_command(). Here, we override qc->scsidone with
-scsi_finish_command() and calls ata_qc_complete().
+either retried with :c:func:`scsi_queue_insert` or finished with
+:c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
+:c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.
 
 If EH is invoked due to a failed ATAPI qc, the qc here is completed but
 not deallocated. The purpose of this half-completion is to use the qc as

@@ -565,11 +567,11 @@ place holder to make EH code reach this place. This is a bit hackish,
 but it works.
 
 Once control reaches here, the qc is deallocated by invoking
-__ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE
+:c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE
 is issued. Once sense data is acquired, scmd is finished by directly
-invoking scsi_finish_command() on the scmd. Note that as we already
+invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
 have completed and deallocated the qc which was associated with the
-scmd, we don't need to/cannot call ata_qc_complete() again.
+scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.
 
 Problems with the current EH
 ----------------------------

@@ -583,7 +585,7 @@ Problems with the current EH
 -  When handling timeouts, no action is taken to make device forget
    about the timed out command and ready for new commands.
 
--  EH handling via ata_scsi_error() is not properly protected from
+-  EH handling via :c:func:`ata_scsi_error` is not properly protected from
    usual command processing. On EH entrance, the device is not in
    quiescent state. Timed out commands may succeed or fail any time.
    pio_task and atapi_task may still be running.

@@ -622,6 +624,8 @@ libata Core Internals
 .. kernel-doc:: drivers/ata/libata-core.c
    :internal:
 
+.. kernel-doc:: drivers/ata/libata-eh.c
+
 libata SCSI translation/emulation
 =================================
 

2.9.3
---
 Documentation/kernel-hacking/hacking.rst | 179 +++++++++++++++++--------------
 1 file changed, 98 insertions(+), 81 deletions(-)
index 75597e627791..1a456b60a7cf 100644
@@ -56,7 +56,7 @@ interrupts. You can sleep, by calling :c:func:`schedule()`.
 
 In user context, the ``current`` pointer (indicating the task we are
 currently executing) is valid, and :c:func:`in_interrupt()`
-(``include/linux/interrupt.h``) is false.
+(``include/linux/preempt.h``) is false.
 
 .. warning::
 

@@ -114,12 +114,12 @@ time, although different tasklets can run simultaneously.
     Kuznetsov had at the time.
 
 You can tell you are in a softirq (or tasklet) using the
-:c:func:`in_softirq()` macro (``include/linux/interrupt.h``).
+:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
 
 .. warning::
 
-    Beware that this will return a false positive if a bh lock (see
-    below) is held.
+    Beware that this will return a false positive if a
+    :ref:`botton half lock <local_bh_disable>` is held.
 
 Some Basic Rules
 ================

@@ -154,9 +154,7 @@ The Linux kernel is portable
 ioctls: Not writing a new system call
 =====================================
 
-A system call generally looks like this
-
-::
+A system call generally looks like this::
 
     asmlinkage long sys_mycall(int arg)
     {

@@ -175,7 +173,9 @@ If all your routine does is read or write some parameter, consider
 implementing a :c:func:`sysfs()` interface instead.
 
 Inside the ioctl you're in user context to a process. When a error
-occurs you return a negated errno (see ``include/linux/errno.h``),
+occurs you return a negated errno (see
+``include/uapi/asm-generic/errno-base.h``,
+``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
 otherwise you return 0.
 
 After you slept you should check if a signal occurred: the Unix/Linux

@@ -195,9 +195,7 @@ some data structure.
 If you're doing longer computations: first think userspace. If you
 **really** want to do it in kernel you should regularly check if you need
 to give up the CPU (remember there is cooperative multitasking per CPU).
-Idiom:
-
-::
+Idiom::
 
     cond_resched(); /* Will sleep */
 

@@ -231,26 +229,24 @@ Really.
 Common Routines
 ===============
 
-:c:func:`printk()` ``include/linux/kernel.h``
----------------------------------------------
+:c:func:`printk()`
+------------------
+
+Defined in ``include/linux/printk.h``
 
 :c:func:`printk()` feeds kernel messages to the console, dmesg, and
 the syslog daemon. It is useful for debugging and reporting errors, and
 can be used inside interrupt context, but use with caution: a machine
 which has its console flooded with printk messages is unusable. It uses
 a format string mostly compatible with ANSI C printf, and C string
-concatenation to give it a first "priority" argument:
-
-::
+concatenation to give it a first "priority" argument::
 
     printk(KERN_INFO "i = %u\n", i);
 
 
-See ``include/linux/kernel.h``; for other ``KERN_`` values; these are
+See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
 interpreted by syslog as the level. Special case: for printing an IP
-address use
-
-::
+address use::
 
     __be32 ipaddress;
     printk(KERN_INFO "my ip: %pI4\n", &ipaddress);

@@ -270,8 +266,10 @@ overruns. Make sure that will be enough.
     on top of its printf function: "Printf should not be used for
     chit-chat". You should follow that advice.
 
-:c:func:`copy_[to/from]_user()` / :c:func:`get_user()` / :c:func:`put_user()` ``include/linux/uaccess.h``
----------------------------------------------------------------------------------------------------------
+:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
+---------------------------------------------------------------------------------------------------
+
+Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
 
 **[SLEEPS]**
 

@@ -297,8 +295,10 @@ The functions may sleep implicitly. This should never be called outside
 user context (it makes no sense), with interrupts disabled, or a
 spinlock held.
 
-:c:func:`kmalloc()`/:c:func:`kfree()` ``include/linux/slab.h``
---------------------------------------------------------------
+:c:func:`kmalloc()`/:c:func:`kfree()`
+-------------------------------------
+
+Defined in ``include/linux/slab.h``
 
 **[MAY SLEEP: SEE BELOW]**
 

@@ -324,9 +324,9 @@ message, then maybe you called a sleeping allocation function from
 interrupt context without ``GFP_ATOMIC``. You should really fix that.
 Run, don't walk.
 
-If you are allocating at least ``PAGE_SIZE`` (``include/asm/page.h``)
-bytes, consider using :c:func:`__get_free_pages()`
-(``include/linux/mm.h``). It takes an order argument (0 for page sized,
+If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
+``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
+(``include/linux/gfp.h``). It takes an order argument (0 for page sized,
 1 for double page, 2 for four pages etc.) and the same memory priority
 flag word as above.
 

@@ -344,24 +344,30 @@ routine.
 Before inventing your own cache of often-used objects consider using a
 slab cache in ``include/linux/slab.h``
 
-:c:func:`current()` ``include/asm/current.h``
----------------------------------------------
+:c:func:`current()`
+-------------------
+
+Defined in ``include/asm/current.h``
 
 This global variable (really a macro) contains a pointer to the current
 task structure, so is only valid in user context. For example, when a
 process makes a system call, this will point to the task structure of
 the calling process. It is **not NULL** in interrupt context.
 
-:c:func:`mdelay()`/:c:func:`udelay()` ``include/asm/delay.h`` ``include/linux/delay.h``
----------------------------------------------------------------------------------------
+:c:func:`mdelay()`/:c:func:`udelay()`
+-------------------------------------
+
+Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
 
 The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
 used for small pauses. Do not use large values with them as you risk
 overflow - the helper function :c:func:`mdelay()` is useful here, or
 consider :c:func:`msleep()`.
 
-:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` ``include/asm/byteorder.h``
----------------------------------------------------------------------------------------------------------------------------
+:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
+-----------------------------------------------------------------------------------------------
+
+Defined in ``include/asm/byteorder.h``
 
 The :c:func:`cpu_to_be32()` family (where the "32" can be replaced
 by 64 or 16, and the "be" can be replaced by "le") are the general way

@@ -375,8 +381,10 @@ to the given type, and return the converted value. The other variation
 is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
 convert value referred to by the pointer, and return void.
 
-:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` ``include/linux/irqflags.h``
--------------------------------------------------------------------------------------
+:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
+--------------------------------------------------------
+
+Defined in ``include/linux/irqflags.h``
 
 These routines disable hard interrupts on the local CPU, and restore
 them. They are reentrant; saving the previous state in their one

@@ -384,16 +392,23 @@ them. They are reentrant; saving the previous state in their one
 enabled, you can simply use :c:func:`local_irq_disable()` and
 :c:func:`local_irq_enable()`.
 
-:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` ``include/linux/interrupt.h``
---------------------------------------------------------------------------------------
+.. _local_bh_disable:
+
+:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
+--------------------------------------------------------
+
+Defined in ``include/linux/bottom_half.h``
+
 
 These routines disable soft interrupts on the local CPU, and restore
 them. They are reentrant; if soft interrupts were disabled before, they
 will still be disabled after this pair of functions has been called.
 They prevent softirqs and tasklets from running on the current CPU.
 
-:c:func:`smp_processor_id()`() ``include/asm/smp.h``
-----------------------------------------------------
+:c:func:`smp_processor_id()`
+----------------------------
+
+Defined in ``include/linux/smp.h``
 
 :c:func:`get_cpu()` disables preemption (so you won't suddenly get
 moved to another CPU) and returns the current processor number, between

@@ -405,8 +420,10 @@ If you know you cannot be preempted by another task (ie. you are in
 interrupt context, or have preemption disabled) you can use
 smp_processor_id().
 
-``__init``/``__exit``/``__initdata`` ``include/linux/init.h``
--------------------------------------------------------------
+``__init``/``__exit``/``__initdata``
+------------------------------------
+
+Defined in  ``include/linux/init.h``
 
 After boot, the kernel frees up a special section; functions marked with
 ``__init`` and data structures marked with ``__initdata`` are dropped

@@ -415,10 +432,13 @@ initialization. ``__exit`` is used to declare a function which is only
 required on exit: the function will be dropped if this file is not
 compiled as a module. See the header file for use. Note that it makes no
 sense for a function marked with ``__init`` to be exported to modules
-with :c:func:`EXPORT_SYMBOL()` - this will break.
+with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
+will break.
 
-:c:func:`__initcall()`/:c:func:`module_init()` ``include/linux/init.h``
------------------------------------------------------------------------
+:c:func:`__initcall()`/:c:func:`module_init()`
+----------------------------------------------
+
+Defined in  ``include/linux/init.h`` / ``include/linux/module.h``
 
 Many parts of the kernel are well served as a module
 (dynamically-loadable parts of the kernel). Using the

@@ -438,8 +458,11 @@ to fail (unfortunately, this has no effect if the module is compiled
 into the kernel). This function is called in user context with
 interrupts enabled, so it can sleep.
 
-:c:func:`module_exit()` ``include/linux/init.h``
-------------------------------------------------
+:c:func:`module_exit()`
+-----------------------
+
+
+Defined in  ``include/linux/module.h``
 
 This macro defines the function to be called at module removal time (or
 never, in the case of the file compiled into the kernel). It will only

@@ -450,8 +473,10 @@ it returns.
 Note that this macro is optional: if it is not present, your module will
 not be removable (except for 'rmmod -f').
 
-:c:func:`try_module_get()`/:c:func:`module_put()` ``include/linux/module.h``
-----------------------------------------------------------------------------
+:c:func:`try_module_get()`/:c:func:`module_put()`
+-------------------------------------------------
+
+Defined in ``include/linux/module.h``
 
 These manipulate the module usage count, to protect against removal (a
 module also can't be removed if another module uses one of its exported

@@ -472,8 +497,8 @@ Wait Queues ``include/linux/wait.h``
 
 A wait queue is used to wait for someone to wake you up when a certain
 condition is true. They must be used carefully to ensure there is no
-race condition. You declare a ``wait_queue_head_t``, and then processes
-which want to wait for that condition declare a ``wait_queue_t``
+race condition. You declare a :c:type:`wait_queue_head_t`, and then processes
+which want to wait for that condition declare a :c:type:`wait_queue_t`
 referring to themselves, and place that in the queue.
 
 Declaring

@@ -490,15 +515,15 @@ Queuing
 Placing yourself in the waitqueue is fairly complex, because you must
 put yourself in the queue before checking the condition. There is a
 macro to do this: :c:func:`wait_event_interruptible()`
-``include/linux/wait.h`` The first argument is the wait queue head, and
+(``include/linux/wait.h``) The first argument is the wait queue head, and
 the second is an expression which is evaluated; the macro returns 0 when
-this expression is true, or -ERESTARTSYS if a signal is received. The
+this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
 :c:func:`wait_event()` version ignores signals.
 
 Waking Up Queued Tasks
 ----------------------
 
-Call :c:func:`wake_up()` ``include/linux/wait.h``;, which will wake
+Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake
 up every process in the queue. The exception is if one has
 ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
 not be woken. There are other variants of this basic function available

@@ -508,9 +533,9 @@ Atomic Operations
 =================
 
 Certain operations are guaranteed atomic on all platforms. The first
-class of operations work on ``atomic_t`` ``include/asm/atomic.h``; this
-contains a signed integer (at least 32 bits long), and you must use
-these functions to manipulate or read atomic_t variables.
+class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
+this contains a signed integer (at least 32 bits long), and you must use
+these functions to manipulate or read :c:type:`atomic_t` variables.
 :c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
 the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
 :c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and

@@ -534,7 +559,7 @@ true if the bit was previously set; these are particularly useful for
 atomically setting flags.
 
 It is possible to call these operations with bit indices greater than
-BITS_PER_LONG. The resulting behavior is strange on big-endian
+``BITS_PER_LONG``. The resulting behavior is strange on big-endian
 platforms though so it is a good idea not to do this.
 
 Symbols

@@ -546,14 +571,18 @@ be used anywhere in the kernel). However, for modules, a special
 exported symbol table is kept which limits the entry points to the
 kernel proper. Modules can also export symbols.
 
-:c:func:`EXPORT_SYMBOL()` ``include/linux/export.h``
-----------------------------------------------------
+:c:func:`EXPORT_SYMBOL()`
+-------------------------
+
+Defined in ``include/linux/export.h``
 
 This is the classic method of exporting a symbol: dynamically loaded
 modules will be able to use the symbol as normal.
 
-:c:func:`EXPORT_SYMBOL_GPL()` ``include/linux/export.h``
---------------------------------------------------------
+:c:func:`EXPORT_SYMBOL_GPL()`
+-----------------------------
+
+Defined in ``include/linux/export.h``
 
 Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
 exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by

@@ -579,11 +608,11 @@ Return Conventions
 ------------------
 
 For code called in user context, it's very common to defy C convention,
-and return 0 for success, and a negative error number (eg. -EFAULT) for
+and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
 failure. This can be unintuitive at first, but it's fairly widespread in
 the kernel.
 
-Using :c:func:`ERR_PTR()` ``include/linux/err.h``; to encode a
+Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
 negative error number into a pointer, and :c:func:`IS_ERR()` and
 :c:func:`PTR_ERR()` to get it back out again: avoids a separate
 pointer parameter for the error number. Icky, but in a good way.

@@ -603,9 +632,7 @@ Initializing structure members
 ------------------------------
 
 The preferred method of initializing structures is to use designated
-initialisers, as defined by ISO C99, eg:
-
-::
+initialisers, as defined by ISO C99, eg::
 
     static struct block_device_operations opt_fops = {
             .open               = opt_open,

@@ -716,18 +743,14 @@ Kernel Cantrips
 
 Some favorites from browsing the source. Feel free to add to this list.
 
-``arch/x86/include/asm/delay.h:``
-
-::
+``arch/x86/include/asm/delay.h``::
 
     #define ndelay(n) (__builtin_constant_p(n) ? \
             ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
             __ndelay(n))
 
 
-``include/linux/fs.h``:
-
-::
+``include/linux/fs.h``::
 
     /*
      * Kernel pointers have redundant information, so we can use a

@@ -741,9 +764,7 @@ Some favorites from browsing the source. Feel free to add to this list.
      #define PTR_ERR(ptr)    ((long)(ptr))
      #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
 
-``arch/x86/include/asm/uaccess_32.h:``
-
-::
+``arch/x86/include/asm/uaccess_32.h:``::
 
     #define copy_to_user(to,from,n)                         \
             (__builtin_constant_p(n) ?                      \

@@ -751,9 +772,7 @@ Some favorites from browsing the source. Feel free to add to this list.
              __generic_copy_to_user((to),(from),(n)))
 
 
-``arch/sparc/kernel/head.S:``
-
-::
+``arch/sparc/kernel/head.S:``::
 
     /*
      * Sun people can't spell worth damn. "compatability" indeed.

@@ -772,9 +791,7 @@ Some favorites from browsing the source. Feel free to add to this list.
             .asciz "compatible"
 
 
-``arch/sparc/lib/checksum.S:``
-
-::
+``arch/sparc/lib/checksum.S:``::
 
             /* Sun, you just can't beat me, you just can't.  Stop trying,
              * give up.  I'm serious, I am going to kick the living shit

2.9.3
---
 Documentation/dev-tools/kgdb.rst | 489 +++++++++++++++++++--------------------
 1 file changed, 233 insertions(+), 256 deletions(-)
index ea01541806c8..75273203a35a 100644
@@ -51,28 +51,29 @@ Compiling a kernel
 Kernel config options for kgdb
 ------------------------------
 
-To enable ``CONFIG_KGDB`` you should look under "Kernel hacking" /
-"Kernel debugging" and select "KGDB: kernel debugger".
+To enable ``CONFIG_KGDB`` you should look under
+:menuselection:`Kernel hacking --> Kernel debugging` and select
+:menuselection:`KGDB: kernel debugger`.
 
 While it is not a hard requirement that you have symbols in your vmlinux
 file, gdb tends not to be very useful without the symbolic data, so you
-will want to turn on ``CONFIG_DEBUG_INFO`` which is called "Compile the
-kernel with debug info" in the config menu.
+will want to turn on ``CONFIG_DEBUG_INFO`` which is called
+:menuselection:`Compile the kernel with debug info` in the config menu.
 
 It is advised, but not required, that you turn on the
-``CONFIG_FRAME_POINTER`` kernel option which is called "Compile the
-kernel with frame pointers" in the config menu. This option inserts code
+``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
+the kernel with frame pointers` in the config menu. This option inserts code
 to into the compiled executable which saves the frame information in
 registers or on the stack at different points which allows a debugger
 such as gdb to more accurately construct stack back traces while
 debugging the kernel.
 
 If the architecture that you are using supports the kernel option
-CONFIG_STRICT_KERNEL_RWX, you should consider turning it off. This
+``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
 option will prevent the use of software breakpoints because it marks
 certain regions of the kernel's memory space as read-only. If kgdb
 supports it for the architecture you are using, you can use hardware
-breakpoints if you desire to run with the CONFIG_STRICT_KERNEL_RWX
+breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
 option turned on, else you need to turn off this option.
 
 Next you should choose one of more I/O drivers to interconnect debugging

@@ -80,17 +81,14 @@ host and debugged target. Early boot debugging requires a KGDB I/O
 driver that supports early debugging and the driver must be built into
 the kernel directly. Kgdb I/O driver configuration takes place via
 kernel or module parameters which you can learn more about in the in the
-section that describes the parameter "kgdboc".
+section that describes the parameter kgdboc.
 
-Here is an example set of .config symbols to enable or disable for kgdb:
+Here is an example set of ``.config`` symbols to enable or disable for kgdb::
 
--  # CONFIG_STRICT_KERNEL_RWX is not set
-
--  CONFIG_FRAME_POINTER=y
-
--  CONFIG_KGDB=y
-
--  CONFIG_KGDB_SERIAL_CONSOLE=y
+  # CONFIG_STRICT_KERNEL_RWX is not set
+  CONFIG_FRAME_POINTER=y
+  CONFIG_KGDB=y
+  CONFIG_KGDB_SERIAL_CONSOLE=y
 
 Kernel config options for kdb
 -----------------------------

@@ -99,34 +97,29 @@ Kdb is quite a bit more complex than the simple gdbstub sitting on top
 of the kernel's debug core. Kdb must implement a shell, and also adds
 some helper functions in other parts of the kernel, responsible for
 printing out interesting data such as what you would see if you ran
-"lsmod", or "ps". In order to build kdb into the kernel you follow the
+``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
 same steps as you would for kgdb.
 
 The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
-"KGDB_KDB: include kdb frontend for kgdb" in the config menu. In theory
-you would have already also selected an I/O driver such as the
-CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a
+:menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
+In theory you would have already also selected an I/O driver such as the
+``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
 serial port, when you were configuring kgdb.
 
 If you want to use a PS/2-style keyboard with kdb, you would select
-CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as input
-device" in the config menu. The CONFIG_KDB_KEYBOARD option is not used
-for anything in the gdb interface to kgdb. The CONFIG_KDB_KEYBOARD
+``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
+input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
+used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
 option only works with kdb.
 
-Here is an example set of .config symbols to enable/disable kdb:
-
--  # CONFIG_STRICT_KERNEL_RWX is not set
-
--  CONFIG_FRAME_POINTER=y
-
--  CONFIG_KGDB=y
-
--  CONFIG_KGDB_SERIAL_CONSOLE=y
-
--  CONFIG_KGDB_KDB=y
-
--  CONFIG_KDB_KEYBOARD=y
+Here is an example set of ``.config`` symbols to enable/disable kdb::
+
+  # CONFIG_STRICT_KERNEL_RWX is not set
+  CONFIG_FRAME_POINTER=y
+  CONFIG_KGDB=y
+  CONFIG_KGDB_SERIAL_CONSOLE=y
+  CONFIG_KGDB_KDB=y
+  CONFIG_KDB_KEYBOARD=y
 
 Kernel Debugger Boot Arguments
 ==============================

@@ -164,7 +157,9 @@ with kdb while allowing the full graphics console applications to run.
 kgdboc arguments
 ~~~~~~~~~~~~~~~~
 
-Usage: ``kgdboc=[kms][[,]kbd][[,]serial_device][,baud]``
+Usage::
+
+	kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
 
 The order listed above must be observed if you use any of the optional
 configurations together.

@@ -186,11 +181,15 @@ Using loadable module or built-in
 
 1. As a kernel built-in:
 
-   Use the kernel boot argument: ``kgdboc=<tty-device>,[baud]``
+   Use the kernel boot argument::
+
+	kgdboc=<tty-device>,[baud]
 
 2. As a kernel loadable module:
 
-   Use the command: ``modprobe kgdboc kgdboc=<tty-device>,[baud]``
+   Use the command::
+
+	modprobe kgdboc kgdboc=<tty-device>,[baud]
 
    Here are two examples of how you might format the kgdboc string. The
    first is for an x86 target using the first serial port. The second

@@ -206,16 +205,18 @@ Configure kgdboc at runtime with sysfs
 At run time you can enable or disable kgdboc by echoing a parameters
 into the sysfs. Here are two examples:
 
-1. Enable kgdboc on ttyS0
+1. Enable kgdboc on ttyS0::
 
-   ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
 
-2. Disable kgdboc
+2. Disable kgdboc::
 
-   ``echo "" > /sys/module/kgdboc/parameters/kgdboc``
+	echo "" > /sys/module/kgdboc/parameters/kgdboc
 
-NOTE: You do not need to specify the baud if you are configuring the
-console on tty which is already configured or open.
+.. note::
+
+   You do not need to specify the baud if you are configuring the
+   console on tty which is already configured or open.
 
 More examples
 ^^^^^^^^^^^^^

@@ -224,35 +225,42 @@ You can configure kgdboc to use the keyboard, and/or a serial device
 depending on if you are using kdb and/or kgdb, in one of the following
 scenarios.
 
-1. kdb and kgdb over only a serial port
+1. kdb and kgdb over only a serial port::
 
-   ``kgdboc=<serial_device>[,baud]``
+	kgdboc=<serial_device>[,baud]
 
-   Example: ``kgdboc=ttyS0,115200``
+   Example::
 
-2. kdb and kgdb with keyboard and a serial port
+	kgdboc=ttyS0,115200
 
-   ``kgdboc=kbd,<serial_device>[,baud]``
+2. kdb and kgdb with keyboard and a serial port::
 
-   Example: ``kgdboc=kbd,ttyS0,115200``
+	kgdboc=kbd,<serial_device>[,baud]
 
-3. kdb with a keyboard
+   Example::
 
-   ``kgdboc=kbd``
+	kgdboc=kbd,ttyS0,115200
 
-4. kdb with kernel mode setting
+3. kdb with a keyboard::
 
-   ``kgdboc=kms,kbd``
+	kgdboc=kbd
 
-5. kdb with kernel mode setting and kgdb over a serial port
+4. kdb with kernel mode setting::
 
-   ``kgdboc=kms,kbd,ttyS0,115200``
+	kgdboc=kms,kbd
 
-NOTE: Kgdboc does not support interrupting the target via the gdb remote
-protocol. You must manually send a sysrq-g unless you have a proxy that
-splits console output to a terminal program. A console proxy has a
-separate TCP port for the debugger and a separate TCP port for the
-"human" console. The proxy can take care of sending the sysrq-g for you.
+5. kdb with kernel mode setting and kgdb over a serial port::
+
+	kgdboc=kms,kbd,ttyS0,115200
+
+.. note::
+
+   Kgdboc does not support interrupting the target via the gdb remote
+   protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
+   that splits console output to a terminal program. A console proxy has a
+   separate TCP port for the debugger and a separate TCP port for the
+   "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
+   for you.
 
 When using kgdboc with no debugger proxy, you can end up connecting the
 debugger at one of two entry points. If an exception occurs after you

@@ -260,14 +268,14 @@ have loaded kgdboc, a message should print on the console stating it is
 waiting for the debugger. In this case you disconnect your terminal
 program and then connect the debugger in its place. If you want to
 interrupt the target system and forcibly enter a debug session you have
-to issue a Sysrq sequence and then type the letter ``g``. Then you
+to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
 disconnect the terminal session and connect gdb. Your options if you
-don't like this are to hack gdb to send the sysrq-g for you as well as
+don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
 on the initial connect, or to use a debugger proxy that allows an
 unmodified gdb to do the debugging.
 
-Kernel parameter: kgdbwait
---------------------------
+Kernel parameter: ``kgdbwait``
+------------------------------
 
 The Kernel command line option ``kgdbwait`` makes kgdb wait for a
 debugger connection during booting of a kernel. You can only use this

@@ -281,54 +289,64 @@ The kernel will stop and wait as early as the I/O driver and
 architecture allows when you use this option. If you build the kgdb I/O
 driver as a loadable kernel module kgdbwait will not do anything.
 
-Kernel parameter: kgdbcon
--------------------------
+Kernel parameter: ``kgdbcon``
+-----------------------------
 
-The kgdbcon feature allows you to see printk() messages inside gdb while
-gdb is connected to the kernel. Kdb does not make use of the kgdbcon
+The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
+while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
 feature.
 
 Kgdb supports using the gdb serial protocol to send console messages to
 the debugger when the debugger is connected and running. There are two
 ways to activate this feature.
 
-1. Activate with the kernel command line option:
+1. Activate with the kernel command line option::
 
-   ``kgdbcon``
+	kgdbcon
 
-2. Use sysfs before configuring an I/O driver
+2. Use sysfs before configuring an I/O driver::
 
-   ``echo 1 > /sys/module/kgdb/parameters/kgdb_use_con``
+	echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
 
-   NOTE: If you do this after you configure the kgdb I/O driver, the
+.. note::
+
+   If you do this after you configure the kgdb I/O driver, the
    setting will not take effect until the next point the I/O is
    reconfigured.
 
-IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
-active system console. An example of incorrect usage is
-``console=ttyS0,115200 kgdboc=ttyS0 kgdbcon``
+.. important::
+
+   You cannot use kgdboc + kgdbcon on a tty that is an
+   active system console. An example of incorrect usage is::
+
+	console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
 
 It is possible to use this option with kgdboc on a tty that is not a
 system console.
 
-Run time parameter: kgdbreboot
-------------------------------
+Run time parameter: ``kgdbreboot``
+----------------------------------
 
 The kgdbreboot feature allows you to change how the debugger deals with
 the reboot notification. You have 3 choices for the behavior. The
 default behavior is always set to 0.
 
-1. echo -1 > /sys/module/debug_core/parameters/kgdbreboot
+.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
 
-   Ignore the reboot notification entirely.
+.. flat-table::
+  :widths: 1 10 8
 
-2. echo 0 > /sys/module/debug_core/parameters/kgdbreboot
+  * - 1
+    - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
+    - Ignore the reboot notification entirely.
 
-   Send the detach message to any attached debugger client.
+  * - 2
+    - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
+    - Send the detach message to any attached debugger client.
 
-3. echo 1 > /sys/module/debug_core/parameters/kgdbreboot
-
-   Enter the debugger on reboot notify.
+  * - 3
+    - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
+    - Enter the debugger on reboot notify.
 
 Using kdb
 =========

@@ -338,66 +356,56 @@ Quick start for kdb on a serial port
 
 This is a quick example of how to use kdb.
 
-1. Configure kgdboc at boot using kernel parameters:
+1. Configure kgdboc at boot using kernel parameters::
 
-   -  ``console=ttyS0,115200 kgdboc=ttyS0,115200``
+	console=ttyS0,115200 kgdboc=ttyS0,115200
 
    OR
 
    Configure kgdboc after the kernel has booted; assuming you are using
-   a serial port console:
+   a serial port console::
 
-   -  ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
 
 2. Enter the kernel debugger manually or by waiting for an oops or
    fault. There are several ways you can enter the kernel debugger
-   manually; all involve using the sysrq-g, which means you must have
-   enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.
+   manually; all involve using the :kbd:`SysRq-G`, which means you must have
+   enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
 
-   -  When logged in as root or with a super user session you can run:
+   -  When logged in as root or with a super user session you can run::
 
-      ``echo g > /proc/sysrq-trigger``
+	echo g > /proc/sysrq-trigger
 
    -  Example using minicom 2.2
 
-      Press: ``Control-a``
-
-      Press: ``f``
-
-      Press: ``g``
+      Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
 
    -  When you have telneted to a terminal server that supports sending
       a remote break
 
-      Press: ``Control-]``
+      Press: :kbd:`CTRL-]`
 
-      Type in:\ ``send break``
+      Type in: ``send break``
 
-      Press: ``Enter``
+      Press: :kbd:`Enter` :kbd:`g`
 
-      Press: ``g``
-
-3. From the kdb prompt you can run the "help" command to see a complete
+3. From the kdb prompt you can run the ``help`` command to see a complete
    list of the commands that are available.
 
    Some useful commands in kdb include:
 
-   -  lsmod -- Shows where kernel modules are loaded
-
-   -  ps -- Displays only the active processes
-
-   -  ps A -- Shows all the processes
-
-   -  summary -- Shows kernel version info and memory usage
-
-   -  bt -- Get a backtrace of the current process using dump_stack()
-
-   -  dmesg -- View the kernel syslog buffer
-
-   -  go -- Continue the system
+   =========== =================================================================
+   ``lsmod``   Shows where kernel modules are loaded
+   ``ps``      Displays only the active processes
+   ``ps A``    Shows all the processes
+   ``summary`` Shows kernel version info and memory usage
+   ``bt``      Get a backtrace of the current process using :c:func:`dump_stack`
+   ``dmesg``   View the kernel syslog buffer
+   ``go``      Continue the system
+   =========== =================================================================
 
 4. When you are done using kdb you need to consider rebooting the system
-   or using the "go" command to resuming normal kernel execution. If you
+   or using the ``go`` command to resuming normal kernel execution. If you
    have paused the kernel for a lengthy period of time, applications
    that rely on timely networking or anything to do with real wall clock
    time could be adversely affected, so you should take this into

@@ -408,50 +416,50 @@ Quick start for kdb using a keyboard connected console
 
 This is a quick example of how to use kdb with a keyboard.
 
-1. Configure kgdboc at boot using kernel parameters:
+1. Configure kgdboc at boot using kernel parameters::
 
-   -  ``kgdboc=kbd``
+	kgdboc=kbd
 
    OR
 
-   Configure kgdboc after the kernel has booted:
+   Configure kgdboc after the kernel has booted::
 
-   -  ``echo kbd > /sys/module/kgdboc/parameters/kgdboc``
+	echo kbd > /sys/module/kgdboc/parameters/kgdboc
 
 2. Enter the kernel debugger manually or by waiting for an oops or
    fault. There are several ways you can enter the kernel debugger
-   manually; all involve using the sysrq-g, which means you must have
-   enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.
+   manually; all involve using the :kbd:`SysRq-G`, which means you must have
+   enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
 
-   -  When logged in as root or with a super user session you can run:
+   -  When logged in as root or with a super user session you can run::
 
-      ``echo g > /proc/sysrq-trigger``
+	echo g > /proc/sysrq-trigger
 
-   -  Example using a laptop keyboard
+   -  Example using a laptop keyboard:
 
-      Press and hold down: ``Alt``
+      Press and hold down: :kbd:`Alt`
 
-      Press and hold down: ``Fn``
+      Press and hold down: :kbd:`Fn`
 
-      Press and release the key with the label: ``SysRq``
+      Press and release the key with the label: :kbd:`SysRq`
 
-      Release: ``Fn``
+      Release: :kbd:`Fn`
 
-      Press and release: ``g``
+      Press and release: :kbd:`g`
 
-      Release: ``Alt``
+      Release: :kbd:`Alt`
 
    -  Example using a PS/2 101-key keyboard
 
-      Press and hold down: ``Alt``
+      Press and hold down: :kbd:`Alt`
 
-      Press and release the key with the label: ``SysRq``
+      Press and release the key with the label: :kbd:`SysRq`
 
-      Press and release: ``g``
+      Press and release: :kbd:`g`
 
-      Release: ``Alt``
+      Release: :kbd:`Alt`
 
-3. Now type in a kdb command such as "help", "dmesg", "bt" or "go" to
+3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
    continue kernel execution.
 
 Using kgdb / gdb

@@ -477,61 +485,51 @@ Connecting with gdb to a serial port
 
 1. Configure kgdboc
 
-   Configure kgdboc at boot using kernel parameters:
+   Configure kgdboc at boot using kernel parameters::
 
-   -  ``kgdboc=ttyS0,115200``
+	kgdboc=ttyS0,115200
 
    OR
 
-   Configure kgdboc after the kernel has booted:
+   Configure kgdboc after the kernel has booted::
 
-   -  ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
 
 2. Stop kernel execution (break into the debugger)
 
    In order to connect to gdb via kgdboc, the kernel must first be
    stopped. There are several ways to stop the kernel which include
-   using kgdbwait as a boot argument, via a sysrq-g, or running the
+   using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
    kernel until it takes an exception where it waits for the debugger to
    attach.
 
-   -  When logged in as root or with a super user session you can run:
+   -  When logged in as root or with a super user session you can run::
 
-      ``echo g > /proc/sysrq-trigger``
+	echo g > /proc/sysrq-trigger
 
    -  Example using minicom 2.2
 
-      Press: ``Control-a``
-
-      Press: ``f``
-
-      Press: ``g``
+      Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
 
    -  When you have telneted to a terminal server that supports sending
       a remote break
 
-      Press: ``Control-]``
+      Press: :kbd:`CTRL-]`
 
-      Type in:\ ``send break``
+      Type in: ``send break``
 
-      Press: ``Enter``
-
-      Press: ``g``
+      Press: :kbd:`Enter` :kbd:`g`
 
 3. Connect from gdb
 
-   Example (using a directly connected port):
-
-   ::
+   Example (using a directly connected port)::
 
            % gdb ./vmlinux
            (gdb) set remotebaud 115200
            (gdb) target remote /dev/ttyS0
 
 
-   Example (kgdb to a terminal server on TCP port 2012):
-
-   ::
+   Example (kgdb to a terminal server on TCP port 2012)::
 
            % gdb ./vmlinux
            (gdb) target remote 192.168.2.2:2012

@@ -543,12 +541,13 @@ Connecting with gdb to a serial port
    If you are having problems connecting or something is going seriously
    wrong while debugging, it will most often be the case that you want
    to enable gdb to be verbose about its target communications. You do
-   this prior to issuing the ``target
-       remote`` command by typing in: ``set debug remote 1``
+   this prior to issuing the ``target remote`` command by typing in::
+
+	set debug remote 1
 
 Remember if you continue in gdb, and need to "break in" again, you need
-to issue an other sysrq-g. It is easy to create a simple entry point by
-putting a breakpoint at ``sys_sync`` and then you can run "sync" from a
+to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
+putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
 shell or script to break into the debugger.
 
 kgdb and kdb interoperability

@@ -565,22 +564,26 @@ Switching from kgdb to kdb
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are two ways to switch from kgdb to kdb: you can use gdb to issue
-a maintenance packet, or you can blindly type the command $3#33.
+a maintenance packet, or you can blindly type the command ``$3#33``.
 Whenever the kernel debugger stops in kgdb mode it will print the
 message ``KGDB or $3#33 for KDB``. It is important to note that you have
 to type the sequence correctly in one pass. You cannot type a backspace
 or delete because kgdb will interpret that as part of the debug stream.
 
-1. Change from kgdb to kdb by blindly typing:
+1. Change from kgdb to kdb by blindly typing::
 
-   ``$3#33``
+	$3#33
 
-2. Change from kgdb to kdb with gdb
+2. Change from kgdb to kdb with gdb::
 
-   ``maintenance packet 3``
+	maintenance packet 3
 
-   NOTE: Now you must kill gdb. Typically you press control-z and issue
-   the command: kill -9 %
+   .. note::
+
+     Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
+     the command::
+
+	kill -9 %
 
 Change from kdb to kgdb
 ~~~~~~~~~~~~~~~~~~~~~~~

@@ -592,9 +595,9 @@ shell looks for the typical first commands that gdb would issue with the
 gdb remote protocol and if it sees one of those commands it
 automatically changes into kgdb mode.
 
-1. From kdb issue the command:
+1. From kdb issue the command::
 
-   ``kgdb``
+	kgdb
 
    Now disconnect your terminal program and connect gdb in its place
 

@@ -613,13 +616,7 @@ are things like lsmod, dmesg, ps or possibly some of the memory
 information commands. To see all the kdb commands you can run
 ``monitor help``.
 
-Example:
-
-.. raw:: html
-
-   <div class="informalexample">
-
-::
+Example::
 
     (gdb) monitor ps
     1 idle process (state I) and

@@ -632,30 +629,25 @@ Example:
     0xc78789c0      944        1  0    0   S  0xc7878bf4  sh
     (gdb)
 
-
-.. raw:: html
-
-   </div>
-
 kgdb Test Suite
 ===============
 
 When kgdb is enabled in the kernel config you can also elect to enable
-the config parameter KGDB_TESTS. Turning this on will enable a special
+the config parameter ``KGDB_TESTS``. Turning this on will enable a special
 kgdb I/O module which is designed to test the kgdb internal functions.
 
 The kgdb tests are mainly intended for developers to test the kgdb
 internals as well as a tool for developing a new kgdb architecture
 specific implementation. These tests are not really for end users of the
 Linux kernel. The primary source of documentation would be to look in
-the drivers/misc/kgdbts.c file.
+the ``drivers/misc/kgdbts.c`` file.
 
 The kgdb test suite can also be configured at compile time to run the
 core set of tests by setting the kernel config parameter
-KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
+``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
 regression testing and does not require modifying the kernel boot config
 arguments. If this is turned on, the kgdb test suite can be disabled by
-specifying "kgdbts=" as a kernel boot argument.
+specifying ``kgdbts=`` as a kernel boot argument.
 
 Kernel Debugger Internals
 =========================

@@ -667,7 +659,7 @@ The kernel debugger is organized into a number of components:
 
 1. The debug core
 
-   The debug core is found in kernel/debugger/debug_core.c. It
+   The debug core is found in ``kernel/debugger/debug_core.c``. It
    contains:
 
    -  A generic OS exception handler which includes sync'ing the

@@ -688,20 +680,20 @@ The kernel debugger is organized into a number of components:
 
    -  The structures and callback API for atomic kernel mode setting.
 
-      NOTE: kgdboc is where the kms callbacks are invoked.
+      .. note:: kgdboc is where the kms callbacks are invoked.
 
 2. kgdb arch-specific implementation
 
-   This implementation is generally found in arch/\*/kernel/kgdb.c. As
-   an example, arch/x86/kernel/kgdb.c contains the specifics to
+   This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
+   an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
    implement HW breakpoint as well as the initialization to dynamically
    register and unregister for the trap handlers on this architecture.
    The arch-specific portion implements:
 
    -  contains an arch-specific trap catcher which invokes
-      kgdb_handle_exception() to start kgdb about doing its work
+      :c:func:`kgdb_handle_exception` to start kgdb about doing its work
 
-   -  translation to and from gdb specific packet format to pt_regs
+   -  translation to and from gdb specific packet format to :c:type:`pt_regs`
 
    -  Registration and unregistration of architecture specific trap
       hooks

@@ -714,7 +706,7 @@ The kernel debugger is organized into a number of components:
 
 3. gdbstub frontend (aka kgdb)
 
-   The gdbstub is located in kernel/debug/gdbstub.c. It contains:
+   The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
 
    -  All the logic to implement the gdb serial protocol
 

@@ -733,18 +725,18 @@ The kernel debugger is organized into a number of components:
 
    -  A registration API to register additional kdb shell commands.
 
-      -  A good example of a self-contained kdb module is the "ftdump"
+      -  A good example of a self-contained kdb module is the ``ftdump``
          command for dumping the ftrace buffer. See:
-         kernel/trace/trace_kdb.c
+         ``kernel/trace/trace_kdb.c``
 
       -  For an example of how to dynamically register a new kdb command
          you can build the kdb_hello.ko kernel module from
-         samples/kdb/kdb_hello.c. To build this example you can set
-         CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
-         config. Later run "modprobe kdb_hello" and the next time you
-         enter the kdb shell, you can run the "hello" command.
+         ``samples/kdb/kdb_hello.c``. To build this example you can set
+         ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
+         config. Later run ``modprobe kdb_hello`` and the next time you
+         enter the kdb shell, you can run the ``hello`` command.
 
-   -  The implementation for kdb_printf() which emits messages directly
+   -  The implementation for :c:func:`kdb_printf` which emits messages directly
       to I/O drivers, bypassing the kernel log.
 
    -  SW / HW breakpoint management for the kdb shell

@@ -780,21 +772,24 @@ architecture, and at that point you must create an architecture specific
 kgdb implementation.
 
 There are a few flags which must be set on every architecture in their
-<asm/kgdb.h> file. These are:
+``asm/kgdb.h`` file. These are:
 
--  NUMREGBYTES: The size in bytes of all of the registers, so that we
-   can ensure they will all fit into a packet.
+-  ``NUMREGBYTES``:
+     The size in bytes of all of the registers, so that we
+     can ensure they will all fit into a packet.
 
--  BUFMAX: The size in bytes of the buffer GDB will read into. This must
-   be larger than NUMREGBYTES.
+-  ``BUFMAX``:
+     The size in bytes of the buffer GDB will read into. This must
+     be larger than NUMREGBYTES.
 
--  CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
-   flush_cache_range or flush_icache_range. On some architectures,
-   these functions may not be safe to call on SMP since we keep other
-   CPUs in a holding pattern.
+-  ``CACHE_FLUSH_IS_SAFE``:
+     Set to 1 if it is always safe to call
+     flush_cache_range or flush_icache_range. On some architectures,
+     these functions may not be safe to call on SMP since we keep other
+     CPUs in a holding pattern.
 
 There are also the following functions for the common backend, found in
-kernel/kgdb.c, that must be supplied by the architecture-specific
+``kernel/kgdb.c``, that must be supplied by the architecture-specific
 backend unless marked as (optional), in which case a default function
 maybe used if the architecture does not need to provide a specific
 implementation.

@@ -818,9 +813,9 @@ invokes a callback in the serial core which in turn uses the callback in
 the UART driver.
 
 When using kgdboc with a UART, the UART driver must implement two
-callbacks in the ``struct uart_ops``. Example from drivers/8250.c:
+callbacks in the :c:type:`struct uart_ops <uart_ops>`.
+Example from ``drivers/8250.c``::
 
-::
 
     #ifdef CONFIG_CONSOLE_POLL
         .poll_get_char = serial8250_get_poll_char,

@@ -838,46 +833,41 @@ consider, because failing here is most likely going to mean pressing the
 reset button.
 
 kgdboc and keyboards
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kgdboc driver contains logic to configure communications with an
 attached keyboard. The keyboard infrastructure is only compiled into the
-kernel when CONFIG_KDB_KEYBOARD=y is set in the kernel configuration.
+kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
 
 The core polled keyboard driver driver for PS/2 type keyboards is in
-drivers/char/kdb_keyboard.c. This driver is hooked into the debug core
+``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
 when kgdboc populates the callback in the array called
-``kdb_poll_funcs[]``. The kdb_get_kbd_char() is the top-level
+:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
 function which polls hardware for single character input.
 
 kgdboc and kms
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
 
 The kgdboc driver contains logic to request the graphics display to
-switch to a text context when you are using "kgdboc=kms,kbd", provided
+switch to a text context when you are using ``kgdboc=kms,kbd``, provided
 that you have a video driver which has a frame buffer console and atomic
 kernel mode setting support.
 
 Every time the kernel debugger is entered it calls
-kgdboc_pre_exp_handler() which in turn calls con_debug_enter() in
-the virtual console layer. On resuming kernel execution, the kernel
-debugger calls kgdboc_post_exp_handler() which in turn calls
-con_debug_leave().
+:c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
+in the virtual console layer. On resuming kernel execution, the kernel
+debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
+:c:func:`con_debug_leave`.
 
 Any video driver that wants to be compatible with the kernel debugger
-and the atomic kms callbacks must implement the mode_set_base_atomic,
-fb_debug_enter and fb_debug_leave operations. For the
-fb_debug_enter and fb_debug_leave the option exists to use the
+and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
+``fb_debug_enter`` and ``fb_debug_leave operations``. For the
+``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
 generic drm fb helper functions or implement something custom for the
 hardware. The following example shows the initialization of the
 .mode_set_base_atomic operation in
-drivers/gpu/drm/i915/intel_display.c:
+drivers/gpu/drm/i915/intel_display.c::
 
-.. raw:: html
-
-   <div class="informalexample">
-
-::
 
     static const struct drm_crtc_helper_funcs intel_helper_funcs = {
     [...]

@@ -886,19 +876,10 @@ drivers/gpu/drm/i915/intel_display.c:
     };
 
 
-.. raw:: html
-
-   </div>
-
 Here is an example of how the i915 driver initializes the
 fb_debug_enter and fb_debug_leave functions to use the generic drm
-helpers in drivers/gpu/drm/i915/intel_fb.c:
+helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
 
-.. raw:: html
-
-   <div class="informalexample">
-
-::
 
     static struct fb_ops intelfb_ops = {
     [...]

@@ -908,23 +889,19 @@ helpers in drivers/gpu/drm/i915/intel_fb.c:
     };
 
 
-.. raw:: html
-
-   </div>
-
 Credits
 =======
 
 The following people have contributed to this document:
 
-1. Amit Kale\ [email protected]
+1. Amit Kale <[email protected]>
 
-2. Tom Rini\ [email protected]
+2. Tom Rini <[email protected]>
 
 In March 2008 this document was completely rewritten by:
 
--  Jason Wessel\ [email protected]
+-  Jason Wessel <[email protected]>
 
 In Jan 2010 this document was updated to include kdb.
 
--  Jason Wessel\ [email protected]
+-  Jason Wessel <[email protected]>

2.9.3
---
 lib/Kconfig.kgdb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
index 533f912638ed..ab4ff0eea776 100644
@@ -13,7 +13,7 @@ menuconfig KGDB
 	  CONFIG_FRAME_POINTER to aid in producing more reliable stack
 	  backtraces in the external debugger.  Documentation of
 	  kernel debugger is available at http://kgdb.sourceforge.net
-	  as well as in DocBook form in Documentation/DocBook/.  If
+	  as well as in Documentation/dev-tools/kgdb.rst.  If
 	  unsure, say N.
 
 if KGDB

2.9.3
---
 Documentation/conf.py | 2 ++
 1 file changed, 2 insertions(+)
index ce62723491d4..1d461f0c1cd0 100644
@@ -353,6 +353,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
      'The kernel development community', 'manual'),
+    ('dev-tools/index', 'dev-tools.tex', 'Development tools for the Kernel',
+     'The kernel development community', 'manual'),
     ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
      'The kernel development community', 'manual'),
     ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',

2.9.3
---
 Documentation/00-INDEX         |   2 +
 Documentation/DocBook/Makefile | 275 -----------------------------------------
 Documentation/DocBook/lsm.tmpl | 265 ---------------------------------------
 Documentation/lsm.txt          | 201 ++++++++++++++++++++++++++++++
 4 files changed, 203 insertions(+), 540 deletions(-)
 delete mode 100644 Documentation/DocBook/lsm.tmpl
 create mode 100644 Documentation/lsm.txt
index 793acf999e9e..8c2a66e176b9 100644
@@ -264,6 +264,8 @@ logo.gif
 	- full colour GIF image of Linux logo (penguin - Tux).
 logo.txt
 	- info on creator of above logo & site to get additional images from.
+lsm.txt
+	- Linux Security Modules: General Security Hooks for Linux
 lzo.txt
 	- kernel LZO decompressor input formats
 m68k/

2.9.3
---
 Documentation/DocBook/Makefile         |   2 +-
 Documentation/DocBook/z8530book.tmpl   | 371 ---------------------------------
 Documentation/networking/index.rst     |   1 +
 Documentation/networking/z8530book.rst | 257 +++++++++++++++++++++++
 4 files changed, 259 insertions(+), 372 deletions(-)
 delete mode 100644 Documentation/DocBook/z8530book.tmpl
 create mode 100644 Documentation/networking/z8530book.rst
index 8a90891c3712..00a61f4ffcff 100644
@@ -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  \
+DOCBOOKS := \
 	    lsm.xml \
 	    mtdnand.xml librs.xml rapidio.xml \
 	    scsi.xml \

index ff652ff279e8..b5bd87e01f52 100644
@@ -7,6 +7,7 @@ Contents:
    :maxdepth: 2
 
    kapi
+   z8530book
 
 .. only::  subproject
 

2.9.3
---
 Documentation/DocBook/Makefile         |   1 -
 Documentation/DocBook/scsi.tmpl        | 409 ---------------------------------
 Documentation/driver-api/index.rst     |   1 +
 Documentation/driver-api/scsi.rst      | 344 +++++++++++++++++++++++++++
 Documentation/networking/z8530book.rst |  15 +-
 5 files changed, 352 insertions(+), 418 deletions(-)
 delete mode 100644 Documentation/DocBook/scsi.tmpl
 create mode 100644 Documentation/driver-api/scsi.rst
index 00a61f4ffcff..3bbda02d6aee 100644
@@ -9,7 +9,6 @@
 DOCBOOKS := \
 	    lsm.xml \
 	    mtdnand.xml librs.xml rapidio.xml \
-	    scsi.xml \
 	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)

index a9687731810e..9589b06e374e 100644
@@ -32,6 +32,7 @@ available subsections can be seen below.
    i2c
    hsi
    edac
+   scsi
    libata
    miscellaneous
    s390-drivers

index 31032ee36081..fea2c40e7973 100644
@@ -170,10 +170,10 @@ This function is very timing critical. When you wish to simply discard
 data the support code provides the function
 :c:func:`z8530_null_rx()` to discard the data.
 
-To active PIO mode sending and receiving the ``
-    z8530_sync_open`` is called. This expects to be passed the network
-device and the channel. Typically this is called from your network
-device open callback. On a failure a non zero error status is returned.
+To active PIO mode sending and receiving the ``z8530_sync_open`` is called.
+This expects to be passed the network device and the channel. Typically
+this is called from your network device open callback. On a failure a
+non zero error status is returned.
 The :c:func:`z8530_sync_close()` function shuts down a PIO
 channel. This must be done before the channel is opened again and before
 the driver shuts down and unloads.

@@ -190,8 +190,7 @@ the close function matching the open mode you used.
 The final supported mode uses a single DMA channel to drive the transmit
 side. As the Z85C30 has a larger FIFO on the receive channel this tends
 to increase the maximum speed a little. This is activated by calling the
-``z8530_sync_txdma_open
-    ``. This returns a non zero error code on failure. The
+``z8530_sync_txdma_open``. This returns a non zero error code on failure. The
 :c:func:`z8530_sync_txdma_close()` function closes down the Z8530
 interface from this mode.
 

@@ -228,8 +227,8 @@ Should you need to retarget the Z8530 driver to another architecture the
 only code that should need changing are the port I/O functions. At the
 moment these assume PC I/O port accesses. This may not be appropriate
 for all platforms. Replacing :c:func:`z8530_read_port()` and
-``z8530_write_port
-    `` is intended to be all that is required to port this driver layer.
+``z8530_write_port`` is intended to be all that is required to port
+this driver layer.
 
 Known Bugs And Assumptions
 ==========================

2.9.3
---
 Documentation/conf.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)
index 1774357150a3..1bad6a4d6348 100644
@@ -345,27 +345,28 @@ if major == 1 and minor > 3:
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
+# Sorted in alphabetical order
 latex_documents = [
-    ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
-     'The kernel development community', 'manual'),
     ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
      'The kernel development community', 'manual'),
     ('core-api/index', 'core-api.tex', 'The kernel core API manual',
      'The kernel development community', 'manual'),
+    ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
+     'The kernel development community', 'manual'),
     ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
      'The kernel development community', 'manual'),
+    ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
+     'The kernel development community', 'manual'),
     ('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
      'The kernel development community', 'manual'),
     ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
      'The kernel development community', 'manual'),
     ('kernel-hacking/index', 'kernel-hacking.tex', 'Kernel Hacking Guides',
      'The kernel development community', 'manual'),
-    ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
-     'The kernel development community', 'manual'),
-    ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
-     'The kernel development community', 'manual'),
     ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
      'The kernel development community', 'manual'),
+    ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
+     'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',
      'The kernel development community', 'manual'),
 ]

2.9.3
---
 Documentation/DocBook/Makefile       |    1 -
 Documentation/DocBook/mtdnand.tmpl   | 1291 ----------------------------------
 Documentation/driver-api/index.rst   |    1 +
 Documentation/driver-api/mtdnand.rst | 1020 +++++++++++++++++++++++++++
 4 files changed, 1021 insertions(+), 1292 deletions(-)
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 create mode 100644 Documentation/driver-api/mtdnand.rst
index 0a82f6253682..226e5e9fc801 100644
@@ -8,7 +8,6 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

deleted file mode 100644
index b442921bca54..000000000000
@@ -1,1291 +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="MTD-NAND-Guide">
- <bookinfo>
-  <title>MTD NAND Driver Programming Interface</title>
-  
-  <authorgroup>
-   <author>
-    <firstname>Thomas</firstname>
-    <surname>Gleixner</surname>
-    <affiliation>
-     <address>
-      <email>[email protected]</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <copyright>
-   <year>2004</year>
-   <holder>Thomas Gleixner</holder>
-  </copyright>
-
-  <legalnotice>
-   <para>
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License version 2 as published by the Free Software Foundation.
-   </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="intro">
-      <title>Introduction</title>
-  <para>
-  	The generic NAND driver supports almost all NAND and AG-AND based
-	chips and connects them to the Memory Technology Devices (MTD)
-	subsystem of the Linux Kernel.
-  </para>
-  <para>
-  	This documentation is provided for developers who want to implement
-	board drivers or filesystem drivers suitable for NAND devices.
-  </para>
-  </chapter>
-  
-  <chapter id="bugs">
-     <title>Known Bugs And Assumptions</title>
-  <para>
-	None.	
-  </para>
-  </chapter>
-
-  <chapter id="dochints">
-     <title>Documentation hints</title>
-     <para>
-     The function and structure docs are autogenerated. Each function and 
-     struct member has a short description which is marked with an [XXX] identifier.
-     The following chapters explain the meaning of those identifiers.
-     </para>
-     <sect1 id="Function_identifiers_XXX">
-	<title>Function identifiers [XXX]</title>
-     	<para>
-	The functions are marked with [XXX] identifiers in the short
-	comment. The identifiers explain the usage and scope of the
-	functions. Following identifiers are used:
-     	</para>
-	<itemizedlist>
-		<listitem><para>
-	  	[MTD Interface]</para><para>
-		These functions provide the interface to the MTD kernel API. 
-		They are not replaceable and provide functionality
-		which is complete hardware independent.
-		</para></listitem>
-		<listitem><para>
-	  	[NAND Interface]</para><para>
-		These functions are exported and provide the interface to the NAND kernel API. 
-		</para></listitem>
-		<listitem><para>
-	  	[GENERIC]</para><para>
-		Generic functions are not replaceable and provide functionality
-		which is complete hardware independent.
-		</para></listitem>
-		<listitem><para>
-	  	[DEFAULT]</para><para>
-		Default functions provide hardware related functionality which is suitable
-		for most of the implementations. These functions can be replaced by the
-		board driver if necessary. Those functions are called via pointers in the
-		NAND chip description structure. The board driver can set the functions which
-		should be replaced by board dependent functions before calling nand_scan().
-		If the function pointer is NULL on entry to nand_scan() then the pointer
-		is set to the default function which is suitable for the detected chip type.
-		</para></listitem>
-	</itemizedlist>
-     </sect1>
-     <sect1 id="Struct_member_identifiers_XXX">
-	<title>Struct member identifiers [XXX]</title>
-     	<para>
-	The struct members are marked with [XXX] identifiers in the 
-	comment. The identifiers explain the usage and scope of the
-	members. Following identifiers are used:
-     	</para>
-	<itemizedlist>
-		<listitem><para>
-	  	[INTERN]</para><para>
-		These members are for NAND driver internal use only and must not be
-		modified. Most of these values are calculated from the chip geometry
-		information which is evaluated during nand_scan().
-		</para></listitem>
-		<listitem><para>
-	  	[REPLACEABLE]</para><para>
-		Replaceable members hold hardware related functions which can be 
-		provided by the board driver. The board driver can set the functions which
-		should be replaced by board dependent functions before calling nand_scan().
-		If the function pointer is NULL on entry to nand_scan() then the pointer
-		is set to the default function which is suitable for the detected chip type.
-		</para></listitem>
-		<listitem><para>
-	  	[BOARDSPECIFIC]</para><para>
-		Board specific members hold hardware related information which must
-		be provided by the board driver. The board driver must set the function
-		pointers and datafields before calling nand_scan().
-		</para></listitem>
-		<listitem><para>
-	  	[OPTIONAL]</para><para>
-		Optional members can hold information relevant for the board driver. The
-		generic NAND driver code does not use this information.
-		</para></listitem>
-	</itemizedlist>
-     </sect1>
-  </chapter>   
-
-  <chapter id="basicboarddriver">
-     	<title>Basic board driver</title>
-	<para>
-		For most boards it will be sufficient to provide just the
-		basic functions and fill out some really board dependent
-		members in the nand chip description structure.
-	</para>
-	<sect1 id="Basic_defines">
-		<title>Basic defines</title>
-		<para>
-			At least you have to provide a nand_chip structure
-			and a storage for the ioremap'ed chip address.
-			You can allocate the nand_chip structure using
-			kmalloc or you can allocate it statically.
-			The NAND chip structure embeds an mtd structure
-			which will be registered to the MTD subsystem.
-			You can extract a pointer to the mtd structure
-			from a nand_chip pointer using the nand_to_mtd()
-			helper.
-		</para>
-		<para>
-			Kmalloc based example
-		</para>
-		<programlisting>
-static struct mtd_info *board_mtd;
-static void __iomem *baseaddr;
-		</programlisting>
-		<para>
-			Static example
-		</para>
-		<programlisting>
-static struct nand_chip board_chip;
-static void __iomem *baseaddr;
-		</programlisting>
-	</sect1>
-	<sect1 id="Partition_defines">
-		<title>Partition defines</title>
-		<para>
-			If you want to divide your device into partitions, then
-			define a partitioning scheme suitable to your board.
-		</para>
-		<programlisting>
-#define NUM_PARTITIONS 2
-static struct mtd_partition partition_info[] = {
-	{ .name = "Flash partition 1",
-	  .offset =  0,
-	  .size =    8 * 1024 * 1024 },
-	{ .name = "Flash partition 2",
-	  .offset =  MTDPART_OFS_NEXT,
-	  .size =    MTDPART_SIZ_FULL },
-};
-		</programlisting>
-	</sect1>
-	<sect1 id="Hardware_control_functions">
-		<title>Hardware control function</title>
-		<para>
-			The hardware control function provides access to the 
-			control pins of the NAND chip(s). 
-			The access can be done by GPIO pins or by address lines.
-			If you use address lines, make sure that the timing
-			requirements are met.
-		</para>
-		<para>
-			<emphasis>GPIO based example</emphasis>
-		</para>
-		<programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
-	switch(cmd){
-		case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
-		case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
-		case NAND_CTL_SETALE: /* Set ALE pin high */ break;
-		case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
-		case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
-		case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
-	}
-}
-		</programlisting>
-		<para>
-			<emphasis>Address lines based example.</emphasis> It's assumed that the
-			nCE pin is driven by a chip select decoder.
-		</para>
-		<programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
-	struct nand_chip *this = mtd_to_nand(mtd);
-	switch(cmd){
-		case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT;  break;
-		case NAND_CTL_CLRCLE: this->IO_ADDR_W &amp;= ~CLE_ADRR_BIT; break;
-		case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT;  break;
-		case NAND_CTL_CLRALE: this->IO_ADDR_W &amp;= ~ALE_ADRR_BIT; break;
-	}
-}
-		</programlisting>
-	</sect1>
-	<sect1 id="Device_ready_function">
-		<title>Device ready function</title>
-		<para>
-			If the hardware interface has the ready busy pin of the NAND chip connected to a
-			GPIO or other accessible I/O pin, this function is used to read back the state of the
-			pin. The function has no arguments and should return 0, if the device is busy (R/B pin 
-			is low) and 1, if the device is ready (R/B pin is high).
-			If the hardware interface does not give access to the ready busy pin, then
-			the function must not be defined and the function pointer this->dev_ready is set to NULL.		
-		</para>
-	</sect1>
-	<sect1 id="Init_function">
-		<title>Init function</title>
-		<para>
-			The init function allocates memory and sets up all the board
-			specific parameters and function pointers. When everything
-			is set up nand_scan() is called. This function tries to
-			detect and identify then chip. If a chip is found all the
-			internal data fields are initialized accordingly.
-			The structure(s) have to be zeroed out first and then filled with the necessary
-			information about the device.
-		</para>
-		<programlisting>
-static int __init board_init (void)
-{
-	struct nand_chip *this;
-	int err = 0;
-
-	/* Allocate memory for MTD device structure and private data */
-	this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL);
-	if (!this) {
-		printk ("Unable to allocate NAND MTD device structure.\n");
-		err = -ENOMEM;
-		goto out;
-	}
-
-	board_mtd = nand_to_mtd(this);
-
-	/* map physical address */
-	baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
-	if (!baseaddr) {
-		printk("Ioremap to access NAND chip failed\n");
-		err = -EIO;
-		goto out_mtd;
-	}
-
-	/* Set address of NAND IO lines */
-	this->IO_ADDR_R = baseaddr;
-	this->IO_ADDR_W = baseaddr;
-	/* Reference hardware control function */
-	this->hwcontrol = board_hwcontrol;
-	/* Set command delay time, see datasheet for correct value */
-	this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
-	/* Assign the device ready function, if available */
-	this->dev_ready = board_dev_ready;
-	this->eccmode = NAND_ECC_SOFT;
-
-	/* Scan to find existence of the device */
-	if (nand_scan (board_mtd, 1)) {
-		err = -ENXIO;
-		goto out_ior;
-	}
-	
-	add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
-	goto out;
-
-out_ior:
-	iounmap(baseaddr);
-out_mtd:
-	kfree (this);
-out:
-	return err;
-}
-module_init(board_init);
-		</programlisting>
-	</sect1>
-	<sect1 id="Exit_function">
-		<title>Exit function</title>
-		<para>
-			The exit function is only necessary if the driver is
-			compiled as a module. It releases all resources which
-			are held by the chip driver and unregisters the partitions
-			in the MTD layer.
-		</para>
-		<programlisting>
-#ifdef MODULE
-static void __exit board_cleanup (void)
-{
-	/* Release resources, unregister device */
-	nand_release (board_mtd);
-
-	/* unmap physical address */
-	iounmap(baseaddr);
-	
-	/* Free the MTD device structure */
-	kfree (mtd_to_nand(board_mtd));
-}
-module_exit(board_cleanup);
-#endif
-		</programlisting>
-	</sect1>
-  </chapter>
-
-  <chapter id="boarddriversadvanced">
-     	<title>Advanced board driver functions</title>
-	<para>
-		This chapter describes the advanced functionality of the NAND
-		driver. For a list of functions which can be overridden by the board
-		driver see the documentation of the nand_chip structure.
-	</para>
-	<sect1 id="Multiple_chip_control">
-		<title>Multiple chip control</title>
-		<para>
-			The nand driver can control chip arrays. Therefore the
-			board driver must provide an own select_chip function. This
-			function must (de)select the requested chip.
-			The function pointer in the nand_chip structure must
-			be set before calling nand_scan(). The maxchip parameter
-			of nand_scan() defines the maximum number of chips to
-			scan for. Make sure that the select_chip function can
-			handle the requested number of chips.
-		</para>
-		<para>
-			The nand driver concatenates the chips to one virtual
-			chip and provides this virtual chip to the MTD layer.
-		</para>
-		<para>
-			<emphasis>Note: The driver can only handle linear chip arrays
-			of equally sized chips. There is no support for
-			parallel arrays which extend the buswidth.</emphasis>
-		</para>
-		<para>
-			<emphasis>GPIO based example</emphasis>
-		</para>
-		<programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
-	/* Deselect all chips, set all nCE pins high */
-	GPIO(BOARD_NAND_NCE) |= 0xff;	
-	if (chip >= 0)
-		GPIO(BOARD_NAND_NCE) &amp;= ~ (1 &lt;&lt; chip);
-}
-		</programlisting>
-		<para>
-			<emphasis>Address lines based example.</emphasis>
-			Its assumed that the nCE pins are connected to an
-			address decoder.
-		</para>
-		<programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
-	struct nand_chip *this = mtd_to_nand(mtd);
-	
-	/* Deselect all chips */
-	this->IO_ADDR_R &amp;= ~BOARD_NAND_ADDR_MASK;
-	this->IO_ADDR_W &amp;= ~BOARD_NAND_ADDR_MASK;
-	switch (chip) {
-	case 0:
-		this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
-		this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
-		break;
-	....	
-	case n:
-		this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
-		this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
-		break;
-	}	
-}
-		</programlisting>
-	</sect1>
-	<sect1 id="Hardware_ECC_support">
-		<title>Hardware ECC support</title>
-		<sect2 id="Functions_and_constants">
-			<title>Functions and constants</title>
-			<para>
-				The nand driver supports three different types of
-				hardware ECC.
-				<itemizedlist>
-				<listitem><para>NAND_ECC_HW3_256</para><para>
-				Hardware ECC generator providing 3 bytes ECC per
-				256 byte.
-				</para>	</listitem>
-				<listitem><para>NAND_ECC_HW3_512</para><para>
-				Hardware ECC generator providing 3 bytes ECC per
-				512 byte.
-				</para>	</listitem>
-				<listitem><para>NAND_ECC_HW6_512</para><para>
-				Hardware ECC generator providing 6 bytes ECC per
-				512 byte.
-				</para>	</listitem>
-				<listitem><para>NAND_ECC_HW8_512</para><para>
-				Hardware ECC generator providing 6 bytes ECC per
-				512 byte.
-				</para>	</listitem>
-				</itemizedlist>
-				If your hardware generator has a different functionality
-				add it at the appropriate place in nand_base.c
-			</para>
-			<para>
-				The board driver must provide following functions:
-				<itemizedlist>
-				<listitem><para>enable_hwecc</para><para>
-				This function is called before reading / writing to
-				the chip. Reset or initialize the hardware generator
-				in this function. The function is called with an
-				argument which let you distinguish between read 
-				and write operations.
-				</para>	</listitem>
-				<listitem><para>calculate_ecc</para><para>
-				This function is called after read / write from / to
-				the chip. Transfer the ECC from the hardware to
-				the buffer. If the option NAND_HWECC_SYNDROME is set
-				then the function is only called on write. See below.
-				</para>	</listitem>
-				<listitem><para>correct_data</para><para>
-				In case of an ECC error this function is called for
-				error detection and correction. Return 1 respectively 2
-				in case the error can be corrected. If the error is
-				not correctable return -1. If your hardware generator
-				matches the default algorithm of the nand_ecc software
-				generator then use the correction function provided
-				by nand_ecc instead of implementing duplicated code.
-				</para>	</listitem>
-				</itemizedlist>
-			</para>
-		</sect2>
-		<sect2 id="Hardware_ECC_with_syndrome_calculation">
-		<title>Hardware ECC with syndrome calculation</title>
-			<para>
-				Many hardware ECC implementations provide Reed-Solomon
-				codes and calculate an error syndrome on read. The syndrome
-				must be converted to a standard Reed-Solomon syndrome
-				before calling the error correction code in the generic
-				Reed-Solomon library.
-			</para>
-			<para>
-				The ECC bytes must be placed immediately after the data
-				bytes in order to make the syndrome generator work. This
-				is contrary to the usual layout used by software ECC. The
-				separation of data and out of band area is not longer
-				possible. The nand driver code handles this layout and
-				the remaining free bytes in the oob area are managed by 
-				the autoplacement code. Provide a matching oob-layout
-				in this case. See rts_from4.c and diskonchip.c for 
-				implementation reference. In those cases we must also
-				use bad block tables on FLASH, because the ECC layout is
-				interfering with the bad block marker positions.
-				See bad block table support for details.
-			</para>
-		</sect2>
-	</sect1>
-	<sect1 id="Bad_Block_table_support">
-		<title>Bad block table support</title>
-		<para>
-			Most NAND chips mark the bad blocks at a defined
-			position in the spare area. Those blocks must 
-			not be erased under any circumstances as the bad 
-			block information would be lost.
-			It is possible to check the bad block mark each
-			time when the blocks are accessed by reading the
-			spare area of the first page in the block. This
-			is time consuming so a bad block table is used.
-		</para>
-		<para>
-			The nand driver supports various types of bad block
-			tables.
-			<itemizedlist>
-			<listitem><para>Per device</para><para>
-			The bad block table contains all bad block information
-			of the device which can consist of multiple chips.
-			</para>	</listitem>
-			<listitem><para>Per chip</para><para>
-			A bad block table is used per chip and contains the
-			bad block information for this particular chip.
-			</para>	</listitem>
-			<listitem><para>Fixed offset</para><para>
-			The bad block table is located at a fixed offset
-			in the chip (device). This applies to various
-			DiskOnChip devices.
-			</para>	</listitem>
-			<listitem><para>Automatic placed</para><para>
-			The bad block table is automatically placed and
-			detected either at the end or at the beginning
-			of a chip (device)
-			</para>	</listitem>
-			<listitem><para>Mirrored tables</para><para>
-			The bad block table is mirrored on the chip (device) to
-			allow updates of the bad block table without data loss.
-			</para>	</listitem>
-			</itemizedlist>
-		</para>
-		<para>	
-			nand_scan() calls the function nand_default_bbt(). 
-			nand_default_bbt() selects appropriate default
-			bad block table descriptors depending on the chip information
-			which was retrieved by nand_scan().
-		</para>
-		<para>
-			The standard policy is scanning the device for bad 
-			blocks and build a ram based bad block table which
-			allows faster access than always checking the
-			bad block information on the flash chip itself.
-		</para>
-		<sect2 id="Flash_based_tables">
-			<title>Flash based tables</title>
-			<para>
-				It may be desired or necessary to keep a bad block table in FLASH.
-				For AG-AND chips this is mandatory, as they have no factory marked
-				bad blocks. They have factory marked good blocks. The marker pattern
-				is erased when the block is erased to be reused. So in case of
-				powerloss before writing the pattern back to the chip this block 
-				would be lost and added to the bad blocks. Therefore we scan the 
-				chip(s) when we detect them the first time for good blocks and 
-				store this information in a bad block table before erasing any 
-				of the blocks.
-			</para>
-			<para>
-				The blocks in which the tables are stored are protected against
-				accidental access by marking them bad in the memory bad block
-				table. The bad block table management functions are allowed
-				to circumvent this protection.
-			</para>
-			<para>
-				The simplest way to activate the FLASH based bad block table support 
-				is to set the option NAND_BBT_USE_FLASH in the bbt_option field of
-				the nand chip structure before calling nand_scan(). For AG-AND
-				chips is this done by default.
-				This activates the default FLASH based bad block table functionality 
-				of the NAND driver. The default bad block table options are
-				<itemizedlist>
-				<listitem><para>Store bad block table per chip</para></listitem>
-				<listitem><para>Use 2 bits per block</para></listitem>
-				<listitem><para>Automatic placement at the end of the chip</para></listitem>
-				<listitem><para>Use mirrored tables with version numbers</para></listitem>
-				<listitem><para>Reserve 4 blocks at the end of the chip</para></listitem>
-				</itemizedlist>
-			</para>
-		</sect2>
-		<sect2 id="User_defined_tables">
-			<title>User defined tables</title>
-			<para>
-				User defined tables are created by filling out a 
-				nand_bbt_descr structure and storing the pointer in the
-				nand_chip structure member bbt_td before calling nand_scan(). 
-				If a mirror table is necessary a second structure must be
-				created and a pointer to this structure must be stored
-				in bbt_md inside the nand_chip structure. If the bbt_md 
-				member is set to NULL then only the main table is used
-				and no scan for the mirrored table is performed.
-			</para>
-			<para>
-				The most important field in the nand_bbt_descr structure
-				is the options field. The options define most of the 
-				table properties. Use the predefined constants from
-				nand.h to define the options.
-				<itemizedlist>
-				<listitem><para>Number of bits per block</para>
-				<para>The supported number of bits is 1, 2, 4, 8.</para></listitem>
-				<listitem><para>Table per chip</para>
-				<para>Setting the constant NAND_BBT_PERCHIP selects that
-				a bad block table is managed for each chip in a chip array.
-				If this option is not set then a per device bad block table
-				is used.</para></listitem>
-				<listitem><para>Table location is absolute</para>
-				<para>Use the option constant NAND_BBT_ABSPAGE and
-				define the absolute page number where the bad block
-				table starts in the field pages. If you have selected bad block
-				tables per chip and you have a multi chip array then the start page
-				must be given for each chip in the chip array. Note: there is no scan
-				for a table ident pattern performed, so the fields 
-				pattern, veroffs, offs, len can be left uninitialized</para></listitem>
-				<listitem><para>Table location is automatically detected</para>
-				<para>The table can either be located in the first or the last good
-				blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place
-				the bad block table at the end of the chip (device). The
-				bad block tables are marked and identified by a pattern which
-				is stored in the spare area of the first page in the block which
-				holds the bad block table. Store a pointer to the pattern  
-				in the pattern field. Further the length of the pattern has to be 
-				stored in len and the offset in the spare area must be given
-				in the offs member of the nand_bbt_descr structure. For mirrored
-				bad block tables different patterns are mandatory.</para></listitem>
-				<listitem><para>Table creation</para>
-				<para>Set the option NAND_BBT_CREATE to enable the table creation
-				if no table can be found during the scan. Usually this is done only 
-				once if a new chip is found. </para></listitem>
-				<listitem><para>Table write support</para>
-				<para>Set the option NAND_BBT_WRITE to enable the table write support.
-				This allows the update of the bad block table(s) in case a block has
-				to be marked bad due to wear. The MTD interface function block_markbad
-				is calling the update function of the bad block table. If the write
-				support is enabled then the table is updated on FLASH.</para>
-				<para>
-				Note: Write support should only be enabled for mirrored tables with
-				version control.
-				</para></listitem>
-				<listitem><para>Table version control</para>
-				<para>Set the option NAND_BBT_VERSION to enable the table version control.
-				It's highly recommended to enable this for mirrored tables with write
-				support. It makes sure that the risk of losing the bad block
-				table information is reduced to the loss of the information about the
-				one worn out block which should be marked bad. The version is stored in
-				4 consecutive bytes in the spare area of the device. The position of
-				the version number is defined by the member veroffs in the bad block table
-				descriptor.</para></listitem>
-				<listitem><para>Save block contents on write</para>
-				<para>
-				In case that the block which holds the bad block table does contain
-				other useful information, set the option NAND_BBT_SAVECONTENT. When
-				the bad block table is written then the whole block is read the bad
-				block table is updated and the block is erased and everything is 
-				written back. If this option is not set only the bad block table
-				is written and everything else in the block is ignored and erased.
-				</para></listitem>
-				<listitem><para>Number of reserved blocks</para>
-				<para>
-				For automatic placement some blocks must be reserved for
-				bad block table storage. The number of reserved blocks is defined 
-				in the maxblocks member of the bad block table description structure.
-				Reserving 4 blocks for mirrored tables should be a reasonable number. 
-				This also limits the number of blocks which are scanned for the bad
-				block table ident pattern.
-				</para></listitem>
-				</itemizedlist>
-			</para>
-		</sect2>
-	</sect1>
-	<sect1 id="Spare_area_placement">
-		<title>Spare area (auto)placement</title>
-		<para>
-			The nand driver implements different possibilities for
-			placement of filesystem data in the spare area, 
-			<itemizedlist>
-			<listitem><para>Placement defined by fs driver</para></listitem>
-			<listitem><para>Automatic placement</para></listitem>
-			</itemizedlist>
-			The default placement function is automatic placement. The
-			nand driver has built in default placement schemes for the
-			various chiptypes. If due to hardware ECC functionality the
-			default placement does not fit then the board driver can
-			provide a own placement scheme.
-		</para>
-		<para>
-			File system drivers can provide a own placement scheme which
-			is used instead of the default placement scheme.
-		</para>
-		<para>
-			Placement schemes are defined by a nand_oobinfo structure
-	     		<programlisting>
-struct nand_oobinfo {
-	int	useecc;
-	int	eccbytes;
-	int	eccpos[24];
-	int	oobfree[8][2];
-};
-	     		</programlisting>
-			<itemizedlist>
-			<listitem><para>useecc</para><para>
-				The useecc member controls the ecc and placement function. The header
-				file include/mtd/mtd-abi.h contains constants to select ecc and
-				placement. MTD_NANDECC_OFF switches off the ecc complete. This is
-				not recommended and available for testing and diagnosis only.
-				MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE
-				selects automatic placement.
-			</para></listitem>
-			<listitem><para>eccbytes</para><para>
-				The eccbytes member defines the number of ecc bytes per page.
-			</para></listitem>
-			<listitem><para>eccpos</para><para>
-				The eccpos array holds the byte offsets in the spare area where
-				the ecc codes are placed.
-			</para></listitem>
-			<listitem><para>oobfree</para><para>
-				The oobfree array defines the areas in the spare area which can be
-				used for automatic placement. The information is given in the format
-				{offset, size}. offset defines the start of the usable area, size the
-				length in bytes. More than one area can be defined. The list is terminated
-				by an {0, 0} entry.
-			</para></listitem>
-			</itemizedlist>
-		</para>
-		<sect2 id="Placement_defined_by_fs_driver">
-			<title>Placement defined by fs driver</title>
-			<para>
-				The calling function provides a pointer to a nand_oobinfo
-				structure which defines the ecc placement. For writes the
-				caller must provide a spare area buffer along with the
-				data buffer. The spare area buffer size is (number of pages) *
-				(size of spare area). For reads the buffer size is
-				(number of pages) * ((size of spare area) + (number of ecc
-				steps per page) * sizeof (int)). The driver stores the
-				result of the ecc check for each tuple in the spare buffer.
-				The storage sequence is 
-			</para>
-			<para>
-				&lt;spare data page 0&gt;&lt;ecc result 0&gt;...&lt;ecc result n&gt;
-			</para>
-			<para>
-				...
-			</para>
-			<para>
-				&lt;spare data page n&gt;&lt;ecc result 0&gt;...&lt;ecc result n&gt;
-			</para>
-			<para>
-				This is a legacy mode used by YAFFS1.
-			</para>
-			<para>
-				If the spare area buffer is NULL then only the ECC placement is
-				done according to the given scheme in the nand_oobinfo structure.
-			</para>
-		</sect2>
-		<sect2 id="Automatic_placement">
-			<title>Automatic placement</title>
-			<para>
-				Automatic placement uses the built in defaults to place the
-				ecc bytes in the spare area. If filesystem data have to be stored /
-				read into the spare area then the calling function must provide a
-				buffer. The buffer size per page is determined by the oobfree array in
-				the nand_oobinfo structure.
-			</para>
-			<para>
-				If the spare area buffer is NULL then only the ECC placement is
-				done according to the default builtin scheme.
-			</para>
-		</sect2>
-	</sect1>	
-	<sect1 id="Spare_area_autoplacement_default">
-		<title>Spare area autoplacement default schemes</title>
-		<sect2 id="pagesize_256">
-			<title>256 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>Autoplace 0</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>Autoplace 1</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>Autoplace 2</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>Autoplace 3</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
-		</sect2>
-		<sect2 id="pagesize_512">
-			<title>512 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the lower 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>reserved</entry>
-<entry>reserved</entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x08 - 0x0F</entry>
-<entry>Autoplace 0 - 7</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
-		</sect2>
-		<sect2 id="pagesize_2048">
-			<title>2048 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>Reserved</entry>
-<entry>Reserved</entry>
-</row>
-<row>
-<entry>0x02-0x27</entry>
-<entry>Autoplace 0 - 37</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x28</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the first 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x29</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the first 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2A</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the first 256 Bytes data in
-this page</entry>
-</row>
-<row>
-<entry>0x2B</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2C</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2D</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2E</entry>
-<entry>ECC byte 6</entry>
-<entry>Error correction code byte 0 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2F</entry>
-<entry>ECC byte 7</entry>
-<entry>Error correction code byte 1 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x30</entry>
-<entry>ECC byte 8</entry>
-<entry>Error correction code byte 2 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x31</entry>
-<entry>ECC byte 9</entry>
-<entry>Error correction code byte 0 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x32</entry>
-<entry>ECC byte 10</entry>
-<entry>Error correction code byte 1 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x33</entry>
-<entry>ECC byte 11</entry>
-<entry>Error correction code byte 2 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x34</entry>
-<entry>ECC byte 12</entry>
-<entry>Error correction code byte 0 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x35</entry>
-<entry>ECC byte 13</entry>
-<entry>Error correction code byte 1 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x36</entry>
-<entry>ECC byte 14</entry>
-<entry>Error correction code byte 2 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x37</entry>
-<entry>ECC byte 15</entry>
-<entry>Error correction code byte 0 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x38</entry>
-<entry>ECC byte 16</entry>
-<entry>Error correction code byte 1 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x39</entry>
-<entry>ECC byte 17</entry>
-<entry>Error correction code byte 2 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3A</entry>
-<entry>ECC byte 18</entry>
-<entry>Error correction code byte 0 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3B</entry>
-<entry>ECC byte 19</entry>
-<entry>Error correction code byte 1 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3C</entry>
-<entry>ECC byte 20</entry>
-<entry>Error correction code byte 2 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3D</entry>
-<entry>ECC byte 21</entry>
-<entry>Error correction code byte 0 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3E</entry>
-<entry>ECC byte 22</entry>
-<entry>Error correction code byte 1 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3F</entry>
-<entry>ECC byte 23</entry>
-<entry>Error correction code byte 2 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-</tbody></tgroup></informaltable>
-		</sect2>
-     	</sect1>
-  </chapter>
-
-  <chapter id="filesystems">
-     	<title>Filesystem support</title>
-	<para>
-		The NAND driver provides all necessary functions for a
-		filesystem via the MTD interface.
-	</para>
-	<para>
-		Filesystems must be aware of the NAND peculiarities and
-		restrictions. One major restrictions of NAND Flash is, that you cannot 
-		write as often as you want to a page. The consecutive writes to a page, 
-		before erasing it again, are restricted to 1-3 writes, depending on the 
-		manufacturers specifications. This applies similar to the spare area. 
-	</para>
-	<para>
-		Therefore NAND aware filesystems must either write in page size chunks
-		or hold a writebuffer to collect smaller writes until they sum up to 
-		pagesize. Available NAND aware filesystems: JFFS2, YAFFS. 		
-	</para>
-	<para>
-		The spare area usage to store filesystem data is controlled by
-		the spare area placement functionality which is described in one
-		of the earlier chapters.
-	</para>
-  </chapter>	
-  <chapter id="tools">
-     	<title>Tools</title>
-	<para>
-		The MTD project provides a couple of helpful tools to handle NAND Flash.
-		<itemizedlist>
-		<listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem>
-		<listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem>
-		<listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem>
-		</itemizedlist>
-	</para>
-	<para>
-		These tools are aware of the NAND restrictions. Please use those tools
-		instead of complaining about errors which are caused by non NAND aware
-		access methods.
-	</para>
-  </chapter>	
-
-  <chapter id="defines">
-     <title>Constants</title>
-     <para>
-     This chapter describes the constants which might be relevant for a driver developer.
-     </para>
-     <sect1 id="Chip_option_constants">
-	<title>Chip option constants</title>
-     	<sect2 id="Constants_for_chip_id_table">
-		<title>Constants for chip id table</title>
-     		<para>
-		These constants are defined in nand.h. They are ored together to describe
-		the chip functionality.
-     		<programlisting>
-/* Buswitdh is 16 bit */
-#define NAND_BUSWIDTH_16	0x00000002
-/* Device supports partial programming without padding */
-#define NAND_NO_PADDING		0x00000004
-/* Chip has cache program function */
-#define NAND_CACHEPRG		0x00000008
-/* Chip has copy back function */
-#define NAND_COPYBACK		0x00000010
-/* AND Chip which has 4 banks and a confusing page / block 
- * assignment. See Renesas datasheet for further information */
-#define NAND_IS_AND		0x00000020
-/* Chip has a array of 4 pages which can be read without
- * additional ready /busy waits */
-#define NAND_4PAGE_ARRAY	0x00000040 
-		</programlisting>
-     		</para>
-     	</sect2>
-     	<sect2 id="Constants_for_runtime_options">
-		<title>Constants for runtime options</title>
-     		<para>
-		These constants are defined in nand.h. They are ored together to describe
-		the functionality.
-     		<programlisting>
-/* The hw ecc generator provides a syndrome instead a ecc value on read 
- * This can only work if we have the ecc bytes directly behind the 
- * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
-#define NAND_HWECC_SYNDROME	0x00020000
-		</programlisting>
-     		</para>
-     	</sect2>
-     </sect1>	
-
-     <sect1 id="EEC_selection_constants">
-	<title>ECC selection constants</title>
-	<para>
-	Use these constants to select the ECC algorithm.
-  	<programlisting>
-/* No ECC. Usage is not recommended ! */
-#define NAND_ECC_NONE		0
-/* Software ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_SOFT		1
-/* Hardware ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_HW3_256	2
-/* Hardware ECC 3 byte ECC per 512 Byte data */
-#define NAND_ECC_HW3_512	3
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW6_512	4
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW8_512	6
-	</programlisting>
-	</para>
-     </sect1>	
-
-     <sect1 id="Hardware_control_related_constants">
-	<title>Hardware control related constants</title>
-	<para>
-	These constants describe the requested hardware access function when
-	the boardspecific hardware control function is called
-  	<programlisting>
-/* Select the chip by setting nCE to low */
-#define NAND_CTL_SETNCE 	1
-/* Deselect the chip by setting nCE to high */
-#define NAND_CTL_CLRNCE		2
-/* Select the command latch by setting CLE to high */
-#define NAND_CTL_SETCLE		3
-/* Deselect the command latch by setting CLE to low */
-#define NAND_CTL_CLRCLE		4
-/* Select the address latch by setting ALE to high */
-#define NAND_CTL_SETALE		5
-/* Deselect the address latch by setting ALE to low */
-#define NAND_CTL_CLRALE		6
-/* Set write protection by setting WP to high. Not used! */
-#define NAND_CTL_SETWP		7
-/* Clear write protection by setting WP to low. Not used! */
-#define NAND_CTL_CLRWP		8
-	</programlisting>
-	</para>
-     </sect1>	
-
-     <sect1 id="Bad_block_table_constants">
-	<title>Bad block table related constants</title>
-	<para>
-	These constants describe the options used for bad block
-	table descriptors.
-  	<programlisting>
-/* Options for the bad block table descriptors */
-
-/* The number of bits used per block in the bbt on the device */
-#define NAND_BBT_NRBITS_MSK	0x0000000F
-#define NAND_BBT_1BIT		0x00000001
-#define NAND_BBT_2BIT		0x00000002
-#define NAND_BBT_4BIT		0x00000004
-#define NAND_BBT_8BIT		0x00000008
-/* The bad block table is in the last good block of the device */
-#define	NAND_BBT_LASTBLOCK	0x00000010
-/* The bbt is at the given page, else we must scan for the bbt */
-#define NAND_BBT_ABSPAGE	0x00000020
-/* bbt is stored per chip on multichip devices */
-#define NAND_BBT_PERCHIP	0x00000080
-/* bbt has a version counter at offset veroffs */
-#define NAND_BBT_VERSION	0x00000100
-/* Create a bbt if none axists */
-#define NAND_BBT_CREATE		0x00000200
-/* Write bbt if necessary */
-#define NAND_BBT_WRITE		0x00001000
-/* Read and write back block contents when writing bbt */
-#define NAND_BBT_SAVECONTENT	0x00002000
-	</programlisting>
-	</para>
-     </sect1>	
-
-  </chapter>
-  	
-  <chapter id="structs">
-     <title>Structures</title>
-     <para>
-     This chapter contains the autogenerated documentation of the structures which are
-     used in the NAND driver and might be relevant for a driver developer. Each  
-     struct member has a short description which is marked with an [XXX] identifier.
-     See the chapter "Documentation hints" for an explanation.
-     </para>
-!Iinclude/linux/mtd/nand.h
-  </chapter>
-
-  <chapter id="pubfunctions">
-     <title>Public Functions Provided</title>
-     <para>
-     This chapter contains the autogenerated documentation of the NAND kernel API functions
-      which are exported. Each function has a short description which is marked with an [XXX] identifier.
-     See the chapter "Documentation hints" for an explanation.
-     </para>
-!Edrivers/mtd/nand/nand_base.c
-!Edrivers/mtd/nand/nand_bbt.c
-!Edrivers/mtd/nand/nand_ecc.c
-  </chapter>
-  
-  <chapter id="intfunctions">
-     <title>Internal Functions Provided</title>
-     <para>
-     This chapter contains the autogenerated documentation of the NAND driver internal functions.
-     Each function has a short description which is marked with an [XXX] identifier.
-     See the chapter "Documentation hints" for an explanation.
-     The functions marked with [DEFAULT] might be relevant for a board driver developer.
-     </para>
-!Idrivers/mtd/nand/nand_base.c
-!Idrivers/mtd/nand/nand_bbt.c
-<!-- No internal functions for kernel-doc:
-X!Idrivers/mtd/nand/nand_ecc.c
--->  
-  </chapter>
-
-  <chapter id="credits">
-     <title>Credits</title>
-	<para>
-		The following people have contributed to the NAND driver:
-		<orderedlist>
-			<listitem><para>Steven J. Hill<email>[email protected]</email></para></listitem>
-			<listitem><para>David Woodhouse<email>[email protected]</email></para></listitem>
-			<listitem><para>Thomas Gleixner<email>[email protected]</email></para></listitem>
-		</orderedlist>
-		A lot of users have provided bugfixes, improvements and helping hands for testing.
-		Thanks a lot.
-	</para>
-	<para>
-		The following people have contributed to this document:
-		<orderedlist>
-			<listitem><para>Thomas Gleixner<email>[email protected]</email></para></listitem>
-		</orderedlist>
-	</para>
-  </chapter>
-</book>

index 1f8517db39c7..3cf1acebc4ee 100644
@@ -34,6 +34,7 @@ available subsections can be seen below.
    edac
    scsi
    libata
+   mtdnand
    miscellaneous
    w1
    rapidio

new file mode 100644
index 000000000000..8723175f955e
@@ -0,0 +1,1020 @@
+=====================================
+MTD NAND Driver Programming Interface
+=====================================
+
+:Author: Thomas Gleixner
+
+Introduction
+============
+
+The generic NAND driver supports almost all NAND and AG-AND based chips
+and connects them to the Memory Technology Devices (MTD) subsystem of
+the Linux Kernel.
+
+This documentation is provided for developers who want to implement
+board drivers or filesystem drivers suitable for NAND devices.
+
+Known Bugs And Assumptions
+==========================
+
+None.
+
+Documentation hints
+===================
+
+The function and structure docs are autogenerated. Each function and
+struct member has a short description which is marked with an [XXX]
+identifier. The following chapters explain the meaning of those
+identifiers.
+
+Function identifiers [XXX]
+--------------------------
+
+The functions are marked with [XXX] identifiers in the short comment.
+The identifiers explain the usage and scope of the functions. Following
+identifiers are used:
+
+-  [MTD Interface]
+
+   These functions provide the interface to the MTD kernel API. They are
+   not replaceable and provide functionality which is complete hardware
+   independent.
+
+-  [NAND Interface]
+
+   These functions are exported and provide the interface to the NAND
+   kernel API.
+
+-  [GENERIC]
+
+   Generic functions are not replaceable and provide functionality which
+   is complete hardware independent.
+
+-  [DEFAULT]
+
+   Default functions provide hardware related functionality which is
+   suitable for most of the implementations. These functions can be
+   replaced by the board driver if necessary. Those functions are called
+   via pointers in the NAND chip description structure. The board driver
+   can set the functions which should be replaced by board dependent
+   functions before calling nand_scan(). If the function pointer is
+   NULL on entry to nand_scan() then the pointer is set to the default
+   function which is suitable for the detected chip type.
+
+Struct member identifiers [XXX]
+-------------------------------
+
+The struct members are marked with [XXX] identifiers in the comment. The
+identifiers explain the usage and scope of the members. Following
+identifiers are used:
+
+-  [INTERN]
+
+   These members are for NAND driver internal use only and must not be
+   modified. Most of these values are calculated from the chip geometry
+   information which is evaluated during nand_scan().
+
+-  [REPLACEABLE]
+
+   Replaceable members hold hardware related functions which can be
+   provided by the board driver. The board driver can set the functions
+   which should be replaced by board dependent functions before calling
+   nand_scan(). If the function pointer is NULL on entry to
+   nand_scan() then the pointer is set to the default function which is
+   suitable for the detected chip type.
+
+-  [BOARDSPECIFIC]
+
+   Board specific members hold hardware related information which must
+   be provided by the board driver. The board driver must set the
+   function pointers and datafields before calling nand_scan().
+
+-  [OPTIONAL]
+
+   Optional members can hold information relevant for the board driver.
+   The generic NAND driver code does not use this information.
+
+Basic board driver
+==================
+
+For most boards it will be sufficient to provide just the basic
+functions and fill out some really board dependent members in the nand
+chip description structure.
+
+Basic defines
+-------------
+
+At least you have to provide a nand_chip structure and a storage for
+the ioremap'ed chip address. You can allocate the nand_chip structure
+using kmalloc or you can allocate it statically. The NAND chip structure
+embeds an mtd structure which will be registered to the MTD subsystem.
+You can extract a pointer to the mtd structure from a nand_chip pointer
+using the nand_to_mtd() helper.
+
+Kmalloc based example
+
+::
+
+    static struct mtd_info *board_mtd;
+    static void __iomem *baseaddr;
+
+
+Static example
+
+::
+
+    static struct nand_chip board_chip;
+    static void __iomem *baseaddr;
+
+
+Partition defines
+-----------------
+
+If you want to divide your device into partitions, then define a
+partitioning scheme suitable to your board.
+
+::
+
+    #define NUM_PARTITIONS 2
+    static struct mtd_partition partition_info[] = {
+        { .name = "Flash partition 1",
+          .offset =  0,
+          .size =    8 * 1024 * 1024 },
+        { .name = "Flash partition 2",
+          .offset =  MTDPART_OFS_NEXT,
+          .size =    MTDPART_SIZ_FULL },
+    };
+
+
+Hardware control function
+-------------------------
+
+The hardware control function provides access to the control pins of the
+NAND chip(s). The access can be done by GPIO pins or by address lines.
+If you use address lines, make sure that the timing requirements are
+met.
+
+*GPIO based example*
+
+::
+
+    static void board_hwcontrol(struct mtd_info *mtd, int cmd)
+    {
+        switch(cmd){
+            case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
+            case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
+            case NAND_CTL_SETALE: /* Set ALE pin high */ break;
+            case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
+            case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
+            case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
+        }
+    }
+
+
+*Address lines based example.* It's assumed that the nCE pin is driven
+by a chip select decoder.
+
+::
+
+    static void board_hwcontrol(struct mtd_info *mtd, int cmd)
+    {
+        struct nand_chip *this = mtd_to_nand(mtd);
+        switch(cmd){
+            case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT;  break;
+            case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break;
+            case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT;  break;
+            case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break;
+        }
+    }
+
+
+Device ready function
+---------------------
+
+If the hardware interface has the ready busy pin of the NAND chip
+connected to a GPIO or other accessible I/O pin, this function is used
+to read back the state of the pin. The function has no arguments and
+should return 0, if the device is busy (R/B pin is low) and 1, if the
+device is ready (R/B pin is high). If the hardware interface does not
+give access to the ready busy pin, then the function must not be defined
+and the function pointer this->dev_ready is set to NULL.
+
+Init function
+-------------
+
+The init function allocates memory and sets up all the board specific
+parameters and function pointers. When everything is set up nand_scan()
+is called. This function tries to detect and identify then chip. If a
+chip is found all the internal data fields are initialized accordingly.
+The structure(s) have to be zeroed out first and then filled with the
+necessary information about the device.
+
+::
+
+    static int __init board_init (void)
+    {
+        struct nand_chip *this;
+        int err = 0;
+
+        /* Allocate memory for MTD device structure and private data */
+        this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL);
+        if (!this) {
+            printk ("Unable to allocate NAND MTD device structure.\n");
+            err = -ENOMEM;
+            goto out;
+        }
+
+        board_mtd = nand_to_mtd(this);
+
+        /* map physical address */
+        baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
+        if (!baseaddr) {
+            printk("Ioremap to access NAND chip failed\n");
+            err = -EIO;
+            goto out_mtd;
+        }
+
+        /* Set address of NAND IO lines */
+        this->IO_ADDR_R = baseaddr;
+        this->IO_ADDR_W = baseaddr;
+        /* Reference hardware control function */
+        this->hwcontrol = board_hwcontrol;
+        /* Set command delay time, see datasheet for correct value */
+        this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
+        /* Assign the device ready function, if available */
+        this->dev_ready = board_dev_ready;
+        this->eccmode = NAND_ECC_SOFT;
+
+        /* Scan to find existence of the device */
+        if (nand_scan (board_mtd, 1)) {
+            err = -ENXIO;
+            goto out_ior;
+        }
+
+        add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
+        goto out;
+
+    out_ior:
+        iounmap(baseaddr);
+    out_mtd:
+        kfree (this);
+    out:
+        return err;
+    }
+    module_init(board_init);
+
+
+Exit function
+-------------
+
+The exit function is only necessary if the driver is compiled as a
+module. It releases all resources which are held by the chip driver and
+unregisters the partitions in the MTD layer.
+
+::
+
+    #ifdef MODULE
+    static void __exit board_cleanup (void)
+    {
+        /* Release resources, unregister device */
+        nand_release (board_mtd);
+
+        /* unmap physical address */
+        iounmap(baseaddr);
+
+        /* Free the MTD device structure */
+        kfree (mtd_to_nand(board_mtd));
+    }
+    module_exit(board_cleanup);
+    #endif
+
+
+Advanced board driver functions
+===============================
+
+This chapter describes the advanced functionality of the NAND driver.
+For a list of functions which can be overridden by the board driver see
+the documentation of the nand_chip structure.
+
+Multiple chip control
+---------------------
+
+The nand driver can control chip arrays. Therefore the board driver must
+provide an own select_chip function. This function must (de)select the
+requested chip. The function pointer in the nand_chip structure must be
+set before calling nand_scan(). The maxchip parameter of nand_scan()
+defines the maximum number of chips to scan for. Make sure that the
+select_chip function can handle the requested number of chips.
+
+The nand driver concatenates the chips to one virtual chip and provides
+this virtual chip to the MTD layer.
+
+*Note: The driver can only handle linear chip arrays of equally sized
+chips. There is no support for parallel arrays which extend the
+buswidth.*
+
+*GPIO based example*
+
+::
+
+    static void board_select_chip (struct mtd_info *mtd, int chip)
+    {
+        /* Deselect all chips, set all nCE pins high */
+        GPIO(BOARD_NAND_NCE) |= 0xff;
+        if (chip >= 0)
+            GPIO(BOARD_NAND_NCE) &= ~ (1 << chip);
+    }
+
+
+*Address lines based example.* Its assumed that the nCE pins are
+connected to an address decoder.
+
+::
+
+    static void board_select_chip (struct mtd_info *mtd, int chip)
+    {
+        struct nand_chip *this = mtd_to_nand(mtd);
+
+        /* Deselect all chips */
+        this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK;
+        this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK;
+        switch (chip) {
+        case 0:
+            this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
+            this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
+            break;
+        ....
+        case n:
+            this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
+            this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
+            break;
+        }
+    }
+
+
+Hardware ECC support
+--------------------
+
+Functions and constants
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The nand driver supports three different types of hardware ECC.
+
+-  NAND_ECC_HW3_256
+
+   Hardware ECC generator providing 3 bytes ECC per 256 byte.
+
+-  NAND_ECC_HW3_512
+
+   Hardware ECC generator providing 3 bytes ECC per 512 byte.
+
+-  NAND_ECC_HW6_512
+
+   Hardware ECC generator providing 6 bytes ECC per 512 byte.
+
+-  NAND_ECC_HW8_512
+
+   Hardware ECC generator providing 6 bytes ECC per 512 byte.
+
+If your hardware generator has a different functionality add it at the
+appropriate place in nand_base.c
+
+The board driver must provide following functions:
+
+-  enable_hwecc
+
+   This function is called before reading / writing to the chip. Reset
+   or initialize the hardware generator in this function. The function
+   is called with an argument which let you distinguish between read and
+   write operations.
+
+-  calculate_ecc
+
+   This function is called after read / write from / to the chip.
+   Transfer the ECC from the hardware to the buffer. If the option
+   NAND_HWECC_SYNDROME is set then the function is only called on
+   write. See below.
+
+-  correct_data
+
+   In case of an ECC error this function is called for error detection
+   and correction. Return 1 respectively 2 in case the error can be
+   corrected. If the error is not correctable return -1. If your
+   hardware generator matches the default algorithm of the nand_ecc
+   software generator then use the correction function provided by
+   nand_ecc instead of implementing duplicated code.
+
+Hardware ECC with syndrome calculation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many hardware ECC implementations provide Reed-Solomon codes and
+calculate an error syndrome on read. The syndrome must be converted to a
+standard Reed-Solomon syndrome before calling the error correction code
+in the generic Reed-Solomon library.
+
+The ECC bytes must be placed immediately after the data bytes in order
+to make the syndrome generator work. This is contrary to the usual
+layout used by software ECC. The separation of data and out of band area
+is not longer possible. The nand driver code handles this layout and the
+remaining free bytes in the oob area are managed by the autoplacement
+code. Provide a matching oob-layout in this case. See rts_from4.c and
+diskonchip.c for implementation reference. In those cases we must also
+use bad block tables on FLASH, because the ECC layout is interfering
+with the bad block marker positions. See bad block table support for
+details.
+
+Bad block table support
+-----------------------
+
+Most NAND chips mark the bad blocks at a defined position in the spare
+area. Those blocks must not be erased under any circumstances as the bad
+block information would be lost. It is possible to check the bad block
+mark each time when the blocks are accessed by reading the spare area of
+the first page in the block. This is time consuming so a bad block table
+is used.
+
+The nand driver supports various types of bad block tables.
+
+-  Per device
+
+   The bad block table contains all bad block information of the device
+   which can consist of multiple chips.
+
+-  Per chip
+
+   A bad block table is used per chip and contains the bad block
+   information for this particular chip.
+
+-  Fixed offset
+
+   The bad block table is located at a fixed offset in the chip
+   (device). This applies to various DiskOnChip devices.
+
+-  Automatic placed
+
+   The bad block table is automatically placed and detected either at
+   the end or at the beginning of a chip (device)
+
+-  Mirrored tables
+
+   The bad block table is mirrored on the chip (device) to allow updates
+   of the bad block table without data loss.
+
+nand_scan() calls the function nand_default_bbt().
+nand_default_bbt() selects appropriate default bad block table
+descriptors depending on the chip information which was retrieved by
+nand_scan().
+
+The standard policy is scanning the device for bad blocks and build a
+ram based bad block table which allows faster access than always
+checking the bad block information on the flash chip itself.
+
+Flash based tables
+~~~~~~~~~~~~~~~~~~
+
+It may be desired or necessary to keep a bad block table in FLASH. For
+AG-AND chips this is mandatory, as they have no factory marked bad
+blocks. They have factory marked good blocks. The marker pattern is
+erased when the block is erased to be reused. So in case of powerloss
+before writing the pattern back to the chip this block would be lost and
+added to the bad blocks. Therefore we scan the chip(s) when we detect
+them the first time for good blocks and store this information in a bad
+block table before erasing any of the blocks.
+
+The blocks in which the tables are stored are protected against
+accidental access by marking them bad in the memory bad block table. The
+bad block table management functions are allowed to circumvent this
+protection.
+
+The simplest way to activate the FLASH based bad block table support is
+to set the option NAND_BBT_USE_FLASH in the bbt_option field of the
+nand chip structure before calling nand_scan(). For AG-AND chips is
+this done by default. This activates the default FLASH based bad block
+table functionality of the NAND driver. The default bad block table
+options are
+
+-  Store bad block table per chip
+
+-  Use 2 bits per block
+
+-  Automatic placement at the end of the chip
+
+-  Use mirrored tables with version numbers
+
+-  Reserve 4 blocks at the end of the chip
+
+User defined tables
+~~~~~~~~~~~~~~~~~~~
+
+User defined tables are created by filling out a nand_bbt_descr
+structure and storing the pointer in the nand_chip structure member
+bbt_td before calling nand_scan(). If a mirror table is necessary a
+second structure must be created and a pointer to this structure must be
+stored in bbt_md inside the nand_chip structure. If the bbt_md member
+is set to NULL then only the main table is used and no scan for the
+mirrored table is performed.
+
+The most important field in the nand_bbt_descr structure is the
+options field. The options define most of the table properties. Use the
+predefined constants from nand.h to define the options.
+
+-  Number of bits per block
+
+   The supported number of bits is 1, 2, 4, 8.
+
+-  Table per chip
+
+   Setting the constant NAND_BBT_PERCHIP selects that a bad block
+   table is managed for each chip in a chip array. If this option is not
+   set then a per device bad block table is used.
+
+-  Table location is absolute
+
+   Use the option constant NAND_BBT_ABSPAGE and define the absolute
+   page number where the bad block table starts in the field pages. If
+   you have selected bad block tables per chip and you have a multi chip
+   array then the start page must be given for each chip in the chip
+   array. Note: there is no scan for a table ident pattern performed, so
+   the fields pattern, veroffs, offs, len can be left uninitialized
+
+-  Table location is automatically detected
+
+   The table can either be located in the first or the last good blocks
+   of the chip (device). Set NAND_BBT_LASTBLOCK to place the bad block
+   table at the end of the chip (device). The bad block tables are
+   marked and identified by a pattern which is stored in the spare area
+   of the first page in the block which holds the bad block table. Store
+   a pointer to the pattern in the pattern field. Further the length of
+   the pattern has to be stored in len and the offset in the spare area
+   must be given in the offs member of the nand_bbt_descr structure.
+   For mirrored bad block tables different patterns are mandatory.
+
+-  Table creation
+
+   Set the option NAND_BBT_CREATE to enable the table creation if no
+   table can be found during the scan. Usually this is done only once if
+   a new chip is found.
+
+-  Table write support
+
+   Set the option NAND_BBT_WRITE to enable the table write support.
+   This allows the update of the bad block table(s) in case a block has
+   to be marked bad due to wear. The MTD interface function
+   block_markbad is calling the update function of the bad block table.
+   If the write support is enabled then the table is updated on FLASH.
+
+   Note: Write support should only be enabled for mirrored tables with
+   version control.
+
+-  Table version control
+
+   Set the option NAND_BBT_VERSION to enable the table version
+   control. It's highly recommended to enable this for mirrored tables
+   with write support. It makes sure that the risk of losing the bad
+   block table information is reduced to the loss of the information
+   about the one worn out block which should be marked bad. The version
+   is stored in 4 consecutive bytes in the spare area of the device. The
+   position of the version number is defined by the member veroffs in
+   the bad block table descriptor.
+
+-  Save block contents on write
+
+   In case that the block which holds the bad block table does contain
+   other useful information, set the option NAND_BBT_SAVECONTENT. When
+   the bad block table is written then the whole block is read the bad
+   block table is updated and the block is erased and everything is
+   written back. If this option is not set only the bad block table is
+   written and everything else in the block is ignored and erased.
+
+-  Number of reserved blocks
+
+   For automatic placement some blocks must be reserved for bad block
+   table storage. The number of reserved blocks is defined in the
+   maxblocks member of the bad block table description structure.
+   Reserving 4 blocks for mirrored tables should be a reasonable number.
+   This also limits the number of blocks which are scanned for the bad
+   block table ident pattern.
+
+Spare area (auto)placement
+--------------------------
+
+The nand driver implements different possibilities for placement of
+filesystem data in the spare area,
+
+-  Placement defined by fs driver
+
+-  Automatic placement
+
+The default placement function is automatic placement. The nand driver
+has built in default placement schemes for the various chiptypes. If due
+to hardware ECC functionality the default placement does not fit then
+the board driver can provide a own placement scheme.
+
+File system drivers can provide a own placement scheme which is used
+instead of the default placement scheme.
+
+Placement schemes are defined by a nand_oobinfo structure
+
+::
+
+    struct nand_oobinfo {
+        int useecc;
+        int eccbytes;
+        int eccpos[24];
+        int oobfree[8][2];
+    };
+
+
+-  useecc
+
+   The useecc member controls the ecc and placement function. The header
+   file include/mtd/mtd-abi.h contains constants to select ecc and
+   placement. MTD_NANDECC_OFF switches off the ecc complete. This is
+   not recommended and available for testing and diagnosis only.
+   MTD_NANDECC_PLACE selects caller defined placement,
+   MTD_NANDECC_AUTOPLACE selects automatic placement.
+
+-  eccbytes
+
+   The eccbytes member defines the number of ecc bytes per page.
+
+-  eccpos
+
+   The eccpos array holds the byte offsets in the spare area where the
+   ecc codes are placed.
+
+-  oobfree
+
+   The oobfree array defines the areas in the spare area which can be
+   used for automatic placement. The information is given in the format
+   {offset, size}. offset defines the start of the usable area, size the
+   length in bytes. More than one area can be defined. The list is
+   terminated by an {0, 0} entry.
+
+Placement defined by fs driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The calling function provides a pointer to a nand_oobinfo structure
+which defines the ecc placement. For writes the caller must provide a
+spare area buffer along with the data buffer. The spare area buffer size
+is (number of pages) \* (size of spare area). For reads the buffer size
+is (number of pages) \* ((size of spare area) + (number of ecc steps per
+page) \* sizeof (int)). The driver stores the result of the ecc check
+for each tuple in the spare buffer. The storage sequence is::
+
+	<spare data page 0><ecc result 0>...<ecc result n>
+
+	...
+
+	<spare data page n><ecc result 0>...<ecc result n>
+
+This is a legacy mode used by YAFFS1.
+
+If the spare area buffer is NULL then only the ECC placement is done
+according to the given scheme in the nand_oobinfo structure.
+
+Automatic placement
+~~~~~~~~~~~~~~~~~~~
+
+Automatic placement uses the built in defaults to place the ecc bytes in
+the spare area. If filesystem data have to be stored / read into the
+spare area then the calling function must provide a buffer. The buffer
+size per page is determined by the oobfree array in the nand_oobinfo
+structure.
+
+If the spare area buffer is NULL then only the ECC placement is done
+according to the default builtin scheme.
+
+Spare area autoplacement default schemes
+----------------------------------------
+
+256 byte pagesize
+~~~~~~~~~~~~~~~~~
+
+======== ================== ===================================================
+Offset   Content            Comment
+======== ================== ===================================================
+0x00     ECC byte 0         Error correction code byte 0
+0x01     ECC byte 1         Error correction code byte 1
+0x02     ECC byte 2         Error correction code byte 2
+0x03     Autoplace 0
+0x04     Autoplace 1
+0x05     Bad block marker   If any bit in this byte is zero, then this
+			    block is bad. This applies only to the first
+			    page in a block. In the remaining pages this
+			    byte is reserved
+0x06     Autoplace 2
+0x07     Autoplace 3
+======== ================== ===================================================
+
+512 byte pagesize
+~~~~~~~~~~~~~~~~~
+
+
+============= ================== ==============================================
+Offset        Content            Comment
+============= ================== ==============================================
+0x00          ECC byte 0         Error correction code byte 0 of the lower
+				 256 Byte data in this page
+0x01          ECC byte 1         Error correction code byte 1 of the lower
+				 256 Bytes of data in this page
+0x02          ECC byte 2         Error correction code byte 2 of the lower
+				 256 Bytes of data in this page
+0x03          ECC byte 3         Error correction code byte 0 of the upper
+				 256 Bytes of data in this page
+0x04          reserved           reserved
+0x05          Bad block marker   If any bit in this byte is zero, then this
+				 block is bad. This applies only to the first
+				 page in a block. In the remaining pages this
+				 byte is reserved
+0x06          ECC byte 4         Error correction code byte 1 of the upper
+				 256 Bytes of data in this page
+0x07          ECC byte 5         Error correction code byte 2 of the upper
+				 256 Bytes of data in this page
+0x08 - 0x0F   Autoplace 0 - 7
+============= ================== ==============================================
+
+2048 byte pagesize
+~~~~~~~~~~~~~~~~~~
+
+=========== ================== ================================================
+Offset      Content            Comment
+=========== ================== ================================================
+0x00        Bad block marker   If any bit in this byte is zero, then this block
+			       is bad. This applies only to the first page in a
+			       block. In the remaining pages this byte is
+			       reserved
+0x01        Reserved           Reserved
+0x02-0x27   Autoplace 0 - 37
+0x28        ECC byte 0         Error correction code byte 0 of the first
+			       256 Byte data in this page
+0x29        ECC byte 1         Error correction code byte 1 of the first
+			       256 Bytes of data in this page
+0x2A        ECC byte 2         Error correction code byte 2 of the first
+			       256 Bytes data in this page
+0x2B        ECC byte 3         Error correction code byte 0 of the second
+			       256 Bytes of data in this page
+0x2C        ECC byte 4         Error correction code byte 1 of the second
+			       256 Bytes of data in this page
+0x2D        ECC byte 5         Error correction code byte 2 of the second
+			       256 Bytes of data in this page
+0x2E        ECC byte 6         Error correction code byte 0 of the third
+			       256 Bytes of data in this page
+0x2F        ECC byte 7         Error correction code byte 1 of the third
+			       256 Bytes of data in this page
+0x30        ECC byte 8         Error correction code byte 2 of the third
+			       256 Bytes of data in this page
+0x31        ECC byte 9         Error correction code byte 0 of the fourth
+			       256 Bytes of data in this page
+0x32        ECC byte 10        Error correction code byte 1 of the fourth
+			       256 Bytes of data in this page
+0x33        ECC byte 11        Error correction code byte 2 of the fourth
+			       256 Bytes of data in this page
+0x34        ECC byte 12        Error correction code byte 0 of the fifth
+			       256 Bytes of data in this page
+0x35        ECC byte 13        Error correction code byte 1 of the fifth
+			       256 Bytes of data in this page
+0x36        ECC byte 14        Error correction code byte 2 of the fifth
+			       256 Bytes of data in this page
+0x37        ECC byte 15        Error correction code byte 0 of the sixth
+			       256 Bytes of data in this page
+0x38        ECC byte 16        Error correction code byte 1 of the sixth
+			       256 Bytes of data in this page
+0x39        ECC byte 17        Error correction code byte 2 of the sixth
+			       256 Bytes of data in this page
+0x3A        ECC byte 18        Error correction code byte 0 of the seventh
+			       256 Bytes of data in this page
+0x3B        ECC byte 19        Error correction code byte 1 of the seventh
+			       256 Bytes of data in this page
+0x3C        ECC byte 20        Error correction code byte 2 of the seventh
+			       256 Bytes of data in this page
+0x3D        ECC byte 21        Error correction code byte 0 of the eighth
+			       256 Bytes of data in this page
+0x3E        ECC byte 22        Error correction code byte 1 of the eighth
+			       256 Bytes of data in this page
+0x3F        ECC byte 23        Error correction code byte 2 of the eighth
+			       256 Bytes of data in this page
+=========== ================== ================================================
+
+Filesystem support
+==================
+
+The NAND driver provides all necessary functions for a filesystem via
+the MTD interface.
+
+Filesystems must be aware of the NAND peculiarities and restrictions.
+One major restrictions of NAND Flash is, that you cannot write as often
+as you want to a page. The consecutive writes to a page, before erasing
+it again, are restricted to 1-3 writes, depending on the manufacturers
+specifications. This applies similar to the spare area.
+
+Therefore NAND aware filesystems must either write in page size chunks
+or hold a writebuffer to collect smaller writes until they sum up to
+pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
+
+The spare area usage to store filesystem data is controlled by the spare
+area placement functionality which is described in one of the earlier
+chapters.
+
+Tools
+=====
+
+The MTD project provides a couple of helpful tools to handle NAND Flash.
+
+-  flasherase, flasheraseall: Erase and format FLASH partitions
+
+-  nandwrite: write filesystem images to NAND FLASH
+
+-  nanddump: dump the contents of a NAND FLASH partitions
+
+These tools are aware of the NAND restrictions. Please use those tools
+instead of complaining about errors which are caused by non NAND aware
+access methods.
+
+Constants
+=========
+
+This chapter describes the constants which might be relevant for a
+driver developer.
+
+Chip option constants
+---------------------
+
+Constants for chip id table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These constants are defined in nand.h. They are ored together to
+describe the chip functionality.
+
+::
+
+    /* Buswitdh is 16 bit */
+    #define NAND_BUSWIDTH_16    0x00000002
+    /* Device supports partial programming without padding */
+    #define NAND_NO_PADDING     0x00000004
+    /* Chip has cache program function */
+    #define NAND_CACHEPRG       0x00000008
+    /* Chip has copy back function */
+    #define NAND_COPYBACK       0x00000010
+    /* AND Chip which has 4 banks and a confusing page / block
+     * assignment. See Renesas datasheet for further information */
+    #define NAND_IS_AND     0x00000020
+    /* Chip has a array of 4 pages which can be read without
+     * additional ready /busy waits */
+    #define NAND_4PAGE_ARRAY    0x00000040
+
+
+Constants for runtime options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These constants are defined in nand.h. They are ored together to
+describe the functionality.
+
+::
+
+    /* The hw ecc generator provides a syndrome instead a ecc value on read
+     * This can only work if we have the ecc bytes directly behind the
+     * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
+    #define NAND_HWECC_SYNDROME 0x00020000
+
+
+ECC selection constants
+-----------------------
+
+Use these constants to select the ECC algorithm.
+
+::
+
+    /* No ECC. Usage is not recommended ! */
+    #define NAND_ECC_NONE       0
+    /* Software ECC 3 byte ECC per 256 Byte data */
+    #define NAND_ECC_SOFT       1
+    /* Hardware ECC 3 byte ECC per 256 Byte data */
+    #define NAND_ECC_HW3_256    2
+    /* Hardware ECC 3 byte ECC per 512 Byte data */
+    #define NAND_ECC_HW3_512    3
+    /* Hardware ECC 6 byte ECC per 512 Byte data */
+    #define NAND_ECC_HW6_512    4
+    /* Hardware ECC 6 byte ECC per 512 Byte data */
+    #define NAND_ECC_HW8_512    6
+
+
+Hardware control related constants
+----------------------------------
+
+These constants describe the requested hardware access function when the
+boardspecific hardware control function is called
+
+::
+
+    /* Select the chip by setting nCE to low */
+    #define NAND_CTL_SETNCE     1
+    /* Deselect the chip by setting nCE to high */
+    #define NAND_CTL_CLRNCE     2
+    /* Select the command latch by setting CLE to high */
+    #define NAND_CTL_SETCLE     3
+    /* Deselect the command latch by setting CLE to low */
+    #define NAND_CTL_CLRCLE     4
+    /* Select the address latch by setting ALE to high */
+    #define NAND_CTL_SETALE     5
+    /* Deselect the address latch by setting ALE to low */
+    #define NAND_CTL_CLRALE     6
+    /* Set write protection by setting WP to high. Not used! */
+    #define NAND_CTL_SETWP      7
+    /* Clear write protection by setting WP to low. Not used! */
+    #define NAND_CTL_CLRWP      8
+
+
+Bad block table related constants
+---------------------------------
+
+These constants describe the options used for bad block table
+descriptors.
+
+::
+
+    /* Options for the bad block table descriptors */
+
+    /* The number of bits used per block in the bbt on the device */
+    #define NAND_BBT_NRBITS_MSK 0x0000000F
+    #define NAND_BBT_1BIT       0x00000001
+    #define NAND_BBT_2BIT       0x00000002
+    #define NAND_BBT_4BIT       0x00000004
+    #define NAND_BBT_8BIT       0x00000008
+    /* The bad block table is in the last good block of the device */
+    #define NAND_BBT_LASTBLOCK  0x00000010
+    /* The bbt is at the given page, else we must scan for the bbt */
+    #define NAND_BBT_ABSPAGE    0x00000020
+    /* bbt is stored per chip on multichip devices */
+    #define NAND_BBT_PERCHIP    0x00000080
+    /* bbt has a version counter at offset veroffs */
+    #define NAND_BBT_VERSION    0x00000100
+    /* Create a bbt if none axists */
+    #define NAND_BBT_CREATE     0x00000200
+    /* Write bbt if necessary */
+    #define NAND_BBT_WRITE      0x00001000
+    /* Read and write back block contents when writing bbt */
+    #define NAND_BBT_SAVECONTENT    0x00002000
+
+
+Structures
+==========
+
+This chapter contains the autogenerated documentation of the structures
+which are used in the NAND driver and might be relevant for a driver
+developer. Each struct member has a short description which is marked
+with an [XXX] identifier. See the chapter "Documentation hints" for an
+explanation.
+
+.. kernel-doc:: include/linux/mtd/nand.h
+   :internal:
+
+Public Functions Provided
+=========================
+
+This chapter contains the autogenerated documentation of the NAND kernel
+API functions which are exported. Each function has a short description
+which is marked with an [XXX] identifier. See the chapter "Documentation
+hints" for an explanation.
+
+.. kernel-doc:: drivers/mtd/nand/nand_base.c
+   :export:
+
+.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
+   :export:
+
+.. kernel-doc:: drivers/mtd/nand/nand_ecc.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the NAND driver
+internal functions. Each function has a short description which is
+marked with an [XXX] identifier. See the chapter "Documentation hints"
+for an explanation. The functions marked with [DEFAULT] might be
+relevant for a board driver developer.
+
+.. kernel-doc:: drivers/mtd/nand/nand_base.c
+   :internal:
+
+.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
+   :internal:
+
+Credits
+=======
+
+The following people have contributed to the NAND driver:
+
+1. Steven J. Hill\ [email protected]
+
+2. David Woodhouse\ [email protected]
+
+3. Thomas Gleixner\ [email protected]
+
+A lot of users have provided bugfixes, improvements and helping hands
+for testing. Thanks a lot.
+
+The following people have contributed to this document:
+
+1. Thomas Gleixner\ [email protected]

---
 Documentation/driver-api/mtdnand.rst | 24 +++++++-----------------
 1 file changed, 7 insertions(+), 17 deletions(-)
index 8723175f955e..7c19795ebb4a 100644
@@ -843,10 +843,8 @@ Chip option constants
 Constants for chip id table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the chip functionality::
 
     /* Buswitdh is 16 bit */
     #define NAND_BUSWIDTH_16    0x00000002

@@ -867,10 +865,8 @@ describe the chip functionality.
 Constants for runtime options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the functionality::
 
     /* The hw ecc generator provides a syndrome instead a ecc value on read
      * This can only work if we have the ecc bytes directly behind the

@@ -881,9 +877,7 @@ describe the functionality.
 ECC selection constants
 -----------------------
 
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
 
     /* No ECC. Usage is not recommended ! */
     #define NAND_ECC_NONE       0

@@ -903,9 +897,7 @@ Hardware control related constants
 ----------------------------------
 
 These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
 
     /* Select the chip by setting nCE to low */
     #define NAND_CTL_SETNCE     1

@@ -929,9 +921,7 @@ Bad block table related constants
 ---------------------------------
 
 These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
 
     /* Options for the bad block table descriptors */
 

---
 Documentation/driver-api/mtdnand.rst | 3 ---
 drivers/mtd/nand/nand_base.c         | 7 +++++--
 include/linux/mtd/nand.h             | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)
index 7c19795ebb4a..e9afa586d15e 100644
@@ -970,9 +970,6 @@ hints" for an explanation.
 .. kernel-doc:: drivers/mtd/nand/nand_base.c
    :export:
 
-.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
-   :export:
-
 .. kernel-doc:: drivers/mtd/nand/nand_ecc.c
    :export:
 

index b0524f8accb6..c8988c01e0d7 100644
@@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
  * specify how to write bad block markers to OOB (chip->block_markbad).
  *
  * We try operations in the following order:
+ *
  *  (1) erase the affected block, to allow OOB marker to be written cleanly
  *  (2) write bad block marker to OOB area of affected block (unless flag
  *      NAND_BBT_NO_OOB_BBM is present)
  *  (3) update the BBT
+ *
  * Note that we retain the first error encountered in (2) or (3), finish the
  * procedures, and dump the error in the end.
 */

@@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
  * @mtd: mtd info
  * @ofs: offset to start unlock from
  * @len: length to unlock
- * @invert: when = 0, unlock the range of blocks within the lower and
+ * @invert:
+ *        - when = 0, unlock the range of blocks within the lower and
  *                    upper boundary address
- *          when = 1, unlock the range of blocks outside the boundaries
+ *        - when = 1, unlock the range of blocks outside the boundaries
  *                    of the lower and upper boundary address
  *
  * Returs unlock status.

index 9591e0fbe5bd..3d5b20379ba3 100644
@@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
  *			Minimum amount of bit errors per @ecc_step_ds guaranteed
  *			to be correctable. If unknown, set to zero.
  * @ecc_step_ds:	[INTERN] ECC step required by the @ecc_strength_ds,
- *                      also from the datasheet. It is the recommended ECC step
+ *			also from the datasheet. It is the recommended ECC step
  *			size, if known; if unknown, set to zero.
  * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
  *			      set to the actually used ONFI mode if the chip is

 include/linux/mutex.h  |  6 +++---
 kernel/futex.c         | 40 ++++++++++++++++++++--------------------
 kernel/locking/mutex.c |  6 +++---
 3 files changed, 26 insertions(+), 26 deletions(-)
index 1127fe31645d..ffcba1f337da 100644
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
  * raisins, and once those are gone this will be removed.
  *
  * Returns:
- *  MUTEX_TRYLOCK_FAILED    - trylock failed,
- *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
- *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ *  - MUTEX_TRYLOCK_FAILED    - trylock failed,
+ *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,
+ *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  */
 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
 mutex_trylock_recursive(struct mutex *lock)

index 357348a6cf6b..b8ae87d227da 100644
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
  *
  * Return: a negative error code or 0
  *
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
  *
  * For shared mappings, it's (page->index, file_inode(vma->vm_file),
  * offset_within_page).  For private mappings, it's (uaddr, current->mm).

@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
  * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
  *
  * Return:
- *  0 - ready to wait;
- *  1 - acquired the lock;
- * <0 - error
+ *  -  0 - ready to wait;
+ *  -  1 - acquired the lock;
+ *  - <0 - error
  *
  * The hb->lock and futex_key refs shall be held by the caller.
  */

@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
  * hb1 and hb2 must be held by the caller.
  *
  * Return:
- *  0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ *  -  0 - failed to acquire the lock atomically;
+ *  - >0 - acquired the lock, return value is vpid of the top_waiter
+ *  - <0 - error
  */
 static int futex_proxy_trylock_atomic(u32 __user *pifutex,
 				 struct futex_hash_bucket *hb1,

@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
  * uaddr2 atomically on behalf of the top waiter.
  *
  * Return:
- * >=0 - on success, the number of tasks requeued or woken;
- *  <0 - on error
+ *  - >=0 - on success, the number of tasks requeued or woken;
+ *  -  <0 - on error
  */
 static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
 			 u32 __user *uaddr2, int nr_wake, int nr_requeue,

@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
  * be paired with exactly one earlier call to queue_me().
  *
  * Return:
- *   1 - if the futex_q was still queued (and we removed unqueued it);
- *   0 - if the futex_q was already removed by the waking thread
+ *  - 1 - if the futex_q was still queued (and we removed unqueued it);
+ *  - 0 - if the futex_q was already removed by the waking thread
  */
 static int unqueue_me(struct futex_q *q)
 {

@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
  * acquire the lock. Must be called with the hb lock held.
  *
  * Return:
- *  1 - success, lock taken;
- *  0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ *  -  1 - success, lock taken;
+ *  -  0 - success, lock not taken;
+ *  - <0 - on error (-EFAULT)
  */
 static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
 {

@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
  * with no q.key reference on failure.
  *
  * Return:
- *  0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ *  -  0 - uaddr contains val and hb has been locked;
+ *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
  */
 static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
 			   struct futex_q *q, struct futex_hash_bucket **hb)

@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
  * called with the hb lock held.
  *
  * Return:
- *  0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ *  -  0 = no early wakeup detected;
+ *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR
  */
 static inline
 int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,

@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
  * If 4 or 7, we cleanup and return with -ETIMEDOUT.
  *
  * Return:
- *  0 - On success;
- * <0 - On error
+ *  -  0 - On success;
+ *  - <0 - On error
  */
 static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
 				 u32 val, ktime_t *abs_time, u32 bitset,

index 198527a62149..858a07590e39 100644
@@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
- *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * checks that will enforce the restrictions and will also do
+ * deadlock debugging)
  *
  * This function is similar to (but not equivalent to) down().
  */

2.9.3
Darren Hart
VMware Open Source Technology Center
---
 Documentation/sphinx/tmplcvt | 28 ----------------------------
 1 file changed, 28 deletions(-)
 delete mode 100755 Documentation/sphinx/tmplcvt
deleted file mode 100755
index 6848f0a26fa5..000000000000
@@ -1,28 +0,0 @@
-#!/bin/bash
-#
-# Convert a template file into something like RST
-#
-# fix <function>
-# feed to pandoc
-# fix \_
-# title line?
-#
-set -eu
-
-if [ "$#" != "2" ]; then
-	echo "$0 <docbook file> <rst file>"
-	exit
-fi
-
-DIR=$(dirname $0)
-
-in=$1
-rst=$2
-tmp=$rst.tmp
-
-cp $in $tmp
-sed --in-place -f $DIR/convert_template.sed $tmp
-pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f $DIR/post_convert.sed $rst
-rm $tmp
-echo "book writen to $rst"

2.9.3
---
 Documentation/doc-guide/kernel-doc.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
index b32e4813ff6f..b24854b5d6be 100644
@@ -149,6 +149,16 @@ Domain`_ references.
 ``%CONST``
   Name of a constant. (No cross-referencing, just formatting.)
 
+````literal````
+  A literal block that should be handled as-is. The output will use a
+  ``monospaced font``.
+
+  Useful if you need to use special characters that would otherwise have some
+  meaning either by kernel-doc script of by reStructuredText.
+
+  This is particularly useful if you need to use things like ``%ph`` inside
+  a function description.
+
 ``$ENVVAR``
   Name of an environment variable. (No cross-referencing, just formatting.)
 

2.9.3
---
 fs/debugfs/inode.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
index e892ae7d89f8..77440e4aa9d4 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/kernel-api for more details.
+ *  See ./Documentation/core-api/kernel-api.rst for more details.
  *
  */
 

2.9.3

 include/linux/mutex.h  |  6 +++---
 kernel/futex.c         | 40 ++++++++++++++++++++--------------------
 kernel/locking/mutex.c |  6 +++---
 3 files changed, 26 insertions(+), 26 deletions(-)
index 1127fe31645d..ffcba1f337da 100644
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
  * raisins, and once those are gone this will be removed.
  *
  * Returns:
- *  MUTEX_TRYLOCK_FAILED    - trylock failed,
- *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
- *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ *  - MUTEX_TRYLOCK_FAILED    - trylock failed,
+ *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,
+ *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  */
 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
 mutex_trylock_recursive(struct mutex *lock)

index 357348a6cf6b..b8ae87d227da 100644
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
  *
  * Return: a negative error code or 0
  *
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
  *
  * For shared mappings, it's (page->index, file_inode(vma->vm_file),
  * offset_within_page).  For private mappings, it's (uaddr, current->mm).

@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
  * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
  *
  * Return:
- *  0 - ready to wait;
- *  1 - acquired the lock;
- * <0 - error
+ *  -  0 - ready to wait;
+ *  -  1 - acquired the lock;
+ *  - <0 - error
  *
  * The hb->lock and futex_key refs shall be held by the caller.
  */

@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
  * hb1 and hb2 must be held by the caller.
  *
  * Return:
- *  0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ *  -  0 - failed to acquire the lock atomically;
+ *  - >0 - acquired the lock, return value is vpid of the top_waiter
+ *  - <0 - error
  */
 static int futex_proxy_trylock_atomic(u32 __user *pifutex,
 				 struct futex_hash_bucket *hb1,

@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
  * uaddr2 atomically on behalf of the top waiter.
  *
  * Return:
- * >=0 - on success, the number of tasks requeued or woken;
- *  <0 - on error
+ *  - >=0 - on success, the number of tasks requeued or woken;
+ *  -  <0 - on error
  */
 static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
 			 u32 __user *uaddr2, int nr_wake, int nr_requeue,

@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
  * be paired with exactly one earlier call to queue_me().
  *
  * Return:
- *   1 - if the futex_q was still queued (and we removed unqueued it);
- *   0 - if the futex_q was already removed by the waking thread
+ *  - 1 - if the futex_q was still queued (and we removed unqueued it);
+ *  - 0 - if the futex_q was already removed by the waking thread
  */
 static int unqueue_me(struct futex_q *q)
 {

@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
  * acquire the lock. Must be called with the hb lock held.
  *
  * Return:
- *  1 - success, lock taken;
- *  0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ *  -  1 - success, lock taken;
+ *  -  0 - success, lock not taken;
+ *  - <0 - on error (-EFAULT)
  */
 static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
 {

@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
  * with no q.key reference on failure.
  *
  * Return:
- *  0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ *  -  0 - uaddr contains val and hb has been locked;
+ *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
  */
 static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
 			   struct futex_q *q, struct futex_hash_bucket **hb)

@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
  * called with the hb lock held.
  *
  * Return:
- *  0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ *  -  0 = no early wakeup detected;
+ *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR
  */
 static inline
 int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,

@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
  * If 4 or 7, we cleanup and return with -ETIMEDOUT.
  *
  * Return:
- *  0 - On success;
- * <0 - On error
+ *  -  0 - On success;
+ *  - <0 - On error
  */
 static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
 				 u32 val, ktime_t *abs_time, u32 bitset,

index 198527a62149..858a07590e39 100644
@@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
- *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * checks that will enforce the restrictions and will also do

+ * deadlock debugging)
  *
  * This function is similar to (but not equivalent to) down().
  */

2.9.3
Darren Hart
VMware Open Source Technology Center
---
 Documentation/conf.py       |  2 ++
 Documentation/sound/conf.py | 10 ++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 Documentation/sound/conf.py
index 1d461f0c1cd0..bca751960dec 100644
@@ -371,6 +371,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',
      'The kernel development community', 'manual'),
+    ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
+     'The kernel development community', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

new file mode 100644
index 000000000000..3f1fc5e74e7b
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Sound Subsystem Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'sound.tex', project,
+     'The kernel development community', 'manual'),
+]

2.9.3
balbi
---
 Documentation/PCI/MSI-HOWTO.txt            |  2 +-
 Documentation/admin-guide/README.rst       |  6 ---
 Documentation/doc-guide/index.rst          |  1 -
 Documentation/doc-guide/sphinx.rst         |  5 ---
 Documentation/fb/api.txt                   |  4 +-
 Documentation/gpu/todo.rst                 |  2 +-
 Documentation/kernel-doc-nano-HOWTO.txt    | 65 +++++-------------------------
 Documentation/process/changes.rst          | 26 +++---------
 Documentation/process/howto.rst            |  8 ----
 Documentation/process/kernel-docs.rst      | 34 +---------------
 Documentation/translations/ja_JP/howto.rst |  7 ----
 Documentation/translations/ko_KR/howto.rst |  7 ----
 12 files changed, 21 insertions(+), 146 deletions(-)
index 1e37138027a3..618e13d5e276 100644
@@ -186,7 +186,7 @@ must disable interrupts while the lock is held.  If the device sends
 a different interrupt, the driver will deadlock trying to recursively
 acquire the spinlock.  Such deadlocks can be avoided by using
 spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
-and acquire the lock (see Documentation/DocBook/kernel-locking).
+and acquire the lock (see Documentation/kernel-hacking/locking.rst).
 
 4.5 How to tell whether MSI/MSI-X is enabled on a device
 

index b96e80f79e85..b5343c5aa224 100644
@@ -55,12 +55,6 @@ Documentation
    contains information about the problems, which may result by upgrading
    your kernel.
 
- - The Documentation/DocBook/ subdirectory contains several guides for
-   kernel developers and users.  These guides can be rendered in a
-   number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
-   After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
-   or ``make mandocs`` will render the documentation in the requested format.
-
 Installing the kernel source
 ----------------------------
 

index 6fff4024606e..a7f95d7d3a63 100644
@@ -10,7 +10,6 @@ How to write kernel documentation
    sphinx.rst
    kernel-doc.rst
    parse-headers.rst
-   docbook.rst
 
 .. only::  subproject and html
 

index 731334de3efd..84e8e8a9cbdb 100644
@@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The
 kernel-doc comments have some special structure and formatting, but beyond that
 they are also treated as reStructuredText.
 
-There is also the deprecated DocBook toolchain to generate documentation from
-DocBook XML template files under ``Documentation/DocBook``. The DocBook files
-are to be converted to reStructuredText, and the toolchain is slated to be
-removed.
-
 Finally, there are thousands of plain text documentation files scattered around
 ``Documentation``. Some of these will likely be converted to reStructuredText
 over time, but the bulk of them will remain in plain text.

index d4ff7de85700..d52cf1e3b975 100644
@@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.
 FOURCC definitions are located in the linux/videodev2.h header. However, and
 despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
 and don't require usage of the V4L2 subsystem. FOURCC documentation is
-available in Documentation/DocBook/v4l/pixfmt.xml.
+available in Documentation/media/uapi/v4l/pixfmt.rst.
 
 To select a format, applications set the grayscale field to the desired FOURCC.
 For YUV formats, they should also select the appropriate colorspace by setting
 the colorspace field to one of the colorspaces listed in linux/videodev2.h and
-documented in Documentation/DocBook/v4l/colorspaces.xml.
+documented in Documentation/media/uapi/v4l/colorspaces.rst.
 
 The red, green, blue and transp fields are not used with the FOURCC-based API.
 For forward compatibility reasons applications must zero those fields, and

index 1bdb7356a310..6162d0e9dc28 100644
@@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The
 task would be to clean up interfaces like moving functions around between
 files to better group them and improving the interfaces like dropping return
 values for functions that never fail. Then write kerneldoc for all exported
-functions and an overview section and integrate it all into the drm DocBook.
+functions and an overview section and integrate it all into the drm book.
 
 See https://dri.freedesktop.org/docs/drm/ for what's there already.
 

index 104740ea0041..c23e2c5ab80d 100644
@@ -17,8 +17,8 @@ The format for this documentation is called the kernel-doc format.
 It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
 
 This style embeds the documentation within the source files, using
-a few simple conventions.  The scripts/kernel-doc perl script, some
-SGML templates in Documentation/DocBook, and other tools understand
+a few simple conventions.  The scripts/kernel-doc perl script, the
+Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
 these conventions, and are used to extract this embedded documentation
 into various documents.
 

@@ -122,15 +122,9 @@ are:
 - scripts/kernel-doc
 
   This is a perl script that hunts for the block comments and can mark
-  them up directly into DocBook, man, text, and HTML. (No, not
+  them up directly into DocBook, ReST, man, text, and HTML. (No, not
   texinfo.)
 
-- Documentation/DocBook/*.tmpl
-
-  These are SGML template files, which are normal SGML files with
-  special place-holders for where the extracted documentation should
-  go.
-
 - scripts/docproc.c
 
   This is a program for converting SGML template files into SGML

@@ -145,25 +139,18 @@ are:
 
 - Makefile
 
-  The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
-  to build XML DocBook files, PostScript files, PDF files, and html files
-  in Documentation/DocBook. The older target 'sgmldocs' is equivalent
-  to 'xmldocs'.
-
-- Documentation/DocBook/Makefile
-
-  This is where C files are associated with SGML templates.
-
+  The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
+  are used to build XML DocBook files, LaTeX files, PDF files,
+  ePub files and html files in Documentation/.
 
 How to extract the documentation
 --------------------------------
 
 If you just want to read the ready-made books on the various
-subsystems (see Documentation/DocBook/*.tmpl), just type 'make
-psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
-preference.  If you would rather read a different format, you can type
-'make xmldocs' and then use DocBook tools to convert
-Documentation/DocBook/*.xml to a format of your choice (for example,
+subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
+depending on your preference.  If you would rather read a different format,
+you can type 'make xmldocs' and then use DocBook tools to convert
+Documentation/output/*.xml to a format of your choice (for example,
 'db2html ...' if 'make htmldocs' was not defined).
 
 If you want to see man pages instead, you can do this:

@@ -329,37 +316,7 @@ This is done by using a DOC: section keyword with a section title.  E.g.:
  * hardware, software, or its subject(s).
  */
 
-DOC: sections are used in SGML templates files as indicated below.
-
-
-How to make new SGML template files
------------------------------------
-
-SGML template files (*.tmpl) are like normal SGML files, except that
-they can contain escape sequences where extracted documentation should
-be inserted.
-
-!E<filename> is replaced by the documentation, in <filename>, for
-functions that are exported using EXPORT_SYMBOL: the function list is
-collected from files listed in Documentation/DocBook/Makefile.
-
-!I<filename> is replaced by the documentation for functions that are
-_not_ exported using EXPORT_SYMBOL.
-
-!D<filename> is used to name additional files to search for functions
-exported using EXPORT_SYMBOL.
-
-!F<filename> <function [functions...]> is replaced by the
-documentation, in <filename>, for the functions listed.
-
-!P<filename> <section title> is replaced by the contents of the DOC:
-section titled <section title> from <filename>.
-Spaces are allowed in <section title>; do not quote the <section title>.
-
-!C<filename> is replaced by nothing, but makes the tools check that
-all DOC: sections and documented functions, symbols, etc. are used.
-This makes sense to use when you use !F/!P only and want to verify
-that all documentation is included.
+DOC: sections are used in ReST files.
 
 Tim.
 */ <[email protected]>

index e25d63f8c0da..3aed751e0cb5 100644
@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
 
 Linux documentation for functions is transitioning to inline
 documentation via specially-formatted comments near their
-definitions in the source.  These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats.  In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
+definitions in the source.  These comments can be combined with ReST
+files the Documentation/ directory to make enriched documentation, which can
+then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
+In order to convert from ReST format to a format of your choice, you'll need
+Sphinx.
 
 Util-linux
 ----------

@@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
   functionalities required for ``XeLaTex`` to work. For PDF output you'll also
   need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
 
-Other tools
------------
-
-In order to produce documentation from DocBook, you'll also need ``xmlto``.
-Please notice, however, that we're currently migrating all documents to use
-``Sphinx``.
 
 Getting updated software
 ========================

@@ -409,15 +402,6 @@ Quota-tools
 
 - <http://sourceforge.net/projects/linuxquota/>
 
-DocBook Stylesheets
--------------------
-
-- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-
-- <http://cyberelk.net/tim/xmlto/>
 
 Intel P6 microcode
 ------------------

index 1260f60d4cb9..c6875b1db56f 100644
@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
 	make latexdocs
 	make epubdocs
 
-Currently, there are some documents written on DocBook that are in
-the process of conversion to ReST. Such documents will be created in the
-Documentation/DocBook/ directory and can be generated also as
-Postscript or man pages by running::
-
-	make psdocs
-	make mandocs
-
 Becoming A Kernel Developer
 ---------------------------
 

index 05a7857a4a83..b8cac85a4001 100644
@@ -40,50 +40,18 @@ Enjoy!
 Docs at the Linux Kernel tree
 -----------------------------
 
-The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
 The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
 
     * Name: **linux/Documentation**
 
       :Author: Many.
       :Location: Documentation/
-      :Keywords: text files, Sphinx, DocBook.
+      :Keywords: text files, Sphinx.
       :Description: Documentation that comes with the kernel sources,
         inside the Documentation directory. Some pages from this document
         (including this document itself) have been moved there, and might
         be more up to date than the web version.
 
-    * Title: **The Kernel Hacking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-hacking.tmpl
-      :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-        symbols, return conventions.
-      :Description: From the Introduction: "Please understand that I
-        never wanted to write this document, being grossly underqualified,
-        but I always wanted to read it, and this was the only way. I
-        simply explain some best practices, and give reading entry-points
-        into the kernel sources. I avoid implementation details: that's
-        what the code is for, and I ignore whole tracts of useful
-        routines. This document assumes familiarity with C, and an
-        understanding of what the kernel is, and how it is used. It was
-        originally written for the 2.3 kernels, but nearly all of it
-        applies to 2.2 too; 2.0 is slightly different".
-
-    * Title: **Linux Kernel Locking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-locking.tmpl
-      :Keywords: locks, locking, spinlock, semaphore, atomic, race
-        condition, bottom halves, tasklets, softirqs.
-      :Description: The title says it all: document describing the
-        locking system in the Linux Kernel either in uniprocessor or SMP
-        systems.
-      :Notes: "It was originally written for the later (>2.3.47) 2.3
-        kernels, but most of it applies to 2.2 too; 2.0 is slightly
-        different". Freely redistributable under the conditions of the GNU
-        General Public License.
-
 On-line docs
 ------------
 

index 4511eed0fabb..8d7ed0cbbf5f 100644
@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
         make latexdocs
         make epubdocs
 
-現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
-す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
-Postscript または man ページの形式を生成するには以下のようにします - ::
-
-        make psdocs
-        make mandocs
-
 カーネル開発者になるには
 ------------------------
 

index 2333697251dd..f06de9ca41a4 100644
@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
          make latexdocs
          make epubdocs
 
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-
 커널 개발자가 되는 것
 ---------------------
 

2.9.3
 124 files changed, 7469 insertions(+), 10511 deletions(-)
 124 files changed, 7469 insertions(+), 10511 deletions(-)
124 files changed, 7469 insertions(+), 10511 deletions(-)
---
 Documentation/dontdiff                    |   1 -
 Documentation/sphinx/convert_template.sed |  18 -
 Documentation/sphinx/post_convert.sed     |  23 -
 MAINTAINERS                               |   3 +-
 Makefile                                  |   1 -
 scripts/.gitignore                        |   1 -
 scripts/Makefile                          |   7 +-
 scripts/docproc.c                         | 681 ------------------------------
 scripts/kernel-doc-xml-ref                | 198 ---------
 9 files changed, 3 insertions(+), 930 deletions(-)
 delete mode 100644 Documentation/sphinx/convert_template.sed
 delete mode 100644 Documentation/sphinx/post_convert.sed
 delete mode 100644 scripts/docproc.c
 delete mode 100755 scripts/kernel-doc-xml-ref
index 77b92221f951..f64a63b233c3 100644
@@ -118,7 +118,6 @@ defkeymap.c
 devlist.h*
 devicetable-offsets.h
 dnotify_test
-docproc
 dslm
 dtc
 elf2ecoff

deleted file mode 100644
index c1503fcca4ec..000000000000
@@ -1,18 +0,0 @@
-#
-# Pandoc doesn't grok <function> or <structname>, so convert them
-# ahead of time.
-#
-# Use the following escapes to pass through pandoc:
-#	$bq = "`"
-#	$lt = "<"
-#	$gt = ">"
-#
-s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1()$bq%g
-s%<function>\([^<(]\+\)</function>%:c:func:$bq\1()$bq%g
-s%<structname>struct *\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
-s%struct <structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
-s%<structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
-#
-# Wrap docproc directives in para and code blocks.
-#
-s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%

deleted file mode 100644
index 392770bac53b..000000000000
@@ -1,23 +0,0 @@
-#
-# Unescape.
-#
-s/$bq/`/g
-s/$lt/</g
-s/$gt/>/g
-#
-# pandoc thinks that both "_" needs to be escaped.  Remove the extra
-# backslashes.
-#
-s/\\_/_/g
-#
-# Unwrap docproc directives.
-#
-s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n   :export:/
-s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n   :internal:/
-s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :functions: \2/
-s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :doc: \2/
-s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
-#
-# Trim trailing whitespace.
-#
-s/[[:space:]]*$//

index 5df61e9757dc..12110616b2d2 100644
@@ -4135,8 +4135,7 @@ M:	Jonathan Corbet <[email protected]>
 L:	[email protected]
 S:	Maintained
 F:	Documentation/
-F:	scripts/docproc.c
-F:	scripts/kernel-doc*
+F:	scripts/kernel-doc
 X:	Documentation/ABI/
 X:	Documentation/devicetree/
 X:	Documentation/acpi

index 855a48c41d61..dd1eb8d6c232 100644
@@ -1467,7 +1467,6 @@ $(help-board-dirs): help-%:
 DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
-	$(Q)$(MAKE) $(build)=scripts build_docproc
 	$(Q)$(MAKE) $(build)=Documentation $@
 
 else # KBUILD_EXTMOD

index e063daa3ec4a..0442c06eefcb 100644
@@ -7,7 +7,6 @@ pnmtologo
 unifdef
 ihex2fw
 recordmcount
-docproc
 check-lc_ctype
 sortextable
 asn1_compiler

index 55550e4141c4..c06f4997d700 100644
@@ -6,7 +6,6 @@
 # pnmttologo:    Convert pnm files to logo files
 # conmakehash:   Create chartable
 # conmakehash:	 Create arrays for initializing the kernel console tables
-# docproc:       Used in Documentation/
 
 HOST_EXTRACFLAGS += -I$(srctree)/tools/include
 

@@ -28,14 +27,12 @@ HOSTLOADLIBES_extract-cert = -lcrypto
 always		:= $(hostprogs-y) $(hostprogs-m)
 
 # The following hostprogs-y programs are only build on demand
-hostprogs-y += unifdef docproc
+hostprogs-y += unifdef
 
 # These targets are used internally to avoid "is up to date" messages
-PHONY += build_unifdef build_docproc
+PHONY += build_unifdef
 build_unifdef: $(obj)/unifdef
 	@:
-build_docproc: $(obj)/docproc
-	@:
 
 subdir-$(CONFIG_MODVERSIONS) += genksyms
 subdir-y                     += mod

2.13.1
Jim
Jim
index a42320385df3..d75c00e3aadb 100644
@@ -95,16 +95,6 @@ endif # HAVE_SPHINX
 # The following targets are independent of HAVE_SPHINX, and the rules should
 # work or silently pass without Sphinx.
 
-# no-ops for the Sphinx toolchain
-sgmldocs:
-	@:
-psdocs:
-	@:
-mandocs:
-	@:
-installmandocs:
-	@:
-
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
 	$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean

index 11be075ba5fa..5f6d09edc9ac 100644
@@ -149,9 +149,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
 核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
 页等不同格式的文档：
     make pdfdocs
-    make psdocs
     make htmldocs
-    make mandocs
 
 
 如何成为内核开发者

index 547947ff87de..5db9c669e541 100644
@@ -1459,7 +1459,7 @@ $(help-board-dirs): help-%:
 
 # Documentation targets
 # ---------------------------------------------------------------------------
-DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
+DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
 	$(Q)$(MAKE) $(build)=Documentation $@

1 file changed, 10 insertions(+)
index b32e4813ff6f..b24854b5d6be 100644
@@ -149,6 +149,16 @@ Domain`_ references.

+  A literal block that should be handled as-is. The output will use a
+  ``monospaced font``.
