Get rid of Docbook

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 \

1,312 lines not on this page · raw message

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'),
+]

794 lines not on this page · raw message

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

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

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
 

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"

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.)
 

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 \

2,151 lines not on this page · raw message

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

838 lines not on this page · raw message

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
 

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
 ------------------------------------

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

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

918 lines not on this page · raw message

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

930 lines not on this page · raw message

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]>

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

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'),
 ]

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'),

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'),
+]

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',

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'),
+]

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

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

381 lines not on this page · raw message

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'),
+]

314 lines not on this page · raw message

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

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.
 
 ::

index 148becd91cba..256e10eedba4 100644
@@ -287,7 +287,6 @@ Transasction Level
 ~~~~~~~~~~~~~~~~~~
 
 .. kernel-doc:: fs/jbd2/transaction.c
-   :export:
 
 See also
 --------

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
 

1,625 lines not on this page · raw message

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

1,027 lines not on this page · raw message

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
 =================================
 

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),)

161 lines not on this page · raw message

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

111 lines not on this page · raw message

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 \

111 lines not on this page · raw message

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`
+

147 lines not on this page · raw message

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 \

371 lines not on this page · raw message

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

257 lines not on this page · raw message

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),)

409 lines not on this page · raw message

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

344 lines not on this page · raw message

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
 ==========================

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

70 lines not on this page · raw message

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),)
 

155 lines not on this page · raw message

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

107 lines not on this page · raw message

index baedb14f3b40..0a82f6253682 100644
@@ -8,7 +8,7 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml librs.xml \
+	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

289 lines not on this page · raw message

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

212 lines not on this page · raw message

index 0a82f6253682..226e5e9fc801 100644
@@ -8,7 +8,6 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

1,291 lines not on this page · raw message

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

1,020 lines not on this page · raw message