Merge tag 'sphinx-4.8' of git://git.lwn.net/linux into topic/drm-misc

Stable tag for sphinx work

Pull current state of the sphinx rework from Jonathan into drm-misc so
that we can start converting gpu.tmpl.

Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

17 files changed, 1326 insertions, 393 deletions

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 000000000000..53752db253e3
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1 @@
+output
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index d70f9b68174e..e0c7e1e0590b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -33,10 +33,6 @@ PDF_METHOD	= $(prefer-db2x)
 PS_METHOD       = $(prefer-db2x)
 
 
-###
-# The targets that may be used.
-PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
-
 targets += $(DOCBOOKS)
 BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
 xmldocs: $(BOOKS)
@@ -63,6 +59,9 @@ installmandocs: mandocs
                 sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \
                 xargs install -m 644 -t /usr/local/man/man9/
 
+# no-op for the DocBook toolchain
+epubdocs:
+
 ###
 #External programs used
 KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
new file mode 100644
index 000000000000..addf32309bc3
--- /dev/null
+++ b/Documentation/Makefile.sphinx
@@ -0,0 +1,63 @@
+# -*- makefile -*-
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXBUILD   = sphinx-build
+SPHINXOPTS    =
+PAPER         =
+BUILDDIR      = $(obj)/output
+
+# User-friendly check for sphinx-build
+HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+ifeq ($(HAVE_SPHINX),0)
+
+.DEFAULT:
+        $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
+        @echo "  SKIP    Sphinx $@ target."
+
+else # HAVE_SPHINX
+
+# User-friendly check for rst2pdf
+HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+KERNELDOC       = $(srctree)/scripts/kernel-doc
+KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
+ALLSPHINXOPTS   = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+quiet_cmd_sphinx = SPHINX  $@
+      cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2
+
+htmldocs:
+        $(call cmd,sphinx,html)
+
+pdfdocs:
+ifeq ($(HAVE_RST2PDF),0)
+        $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)
+        @echo "  SKIP    Sphinx $@ target."
+else # HAVE_RST2PDF
+        $(call cmd,sphinx,pdf)
+endif # HAVE_RST2PDF
+
+epubdocs:
+        $(call cmd,sphinx,epub)
+
+xmldocs:
+        $(call cmd,sphinx,xml)
+
+# no-ops for the Sphinx toolchain
+sgmldocs:
+psdocs:
+mandocs:
+installmandocs:
+
+cleandocs:
+        $(Q)rm -rf $(BUILDDIR)
+
+endif # HAVE_SPHINX
diff --git a/Documentation/conf.py b/Documentation/conf.py
new file mode 100644
index 000000000000..6cc41a0555a3
--- /dev/null
+++ b/Documentation/conf.py
@@ -0,0 +1,414 @@
+# -*- coding: utf-8 -*-
+#
+# The Linux Kernel documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('sphinx'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['kernel-doc']
+
+# Gracefully handle missing rst2pdf.
+try:
+    import rst2pdf
+    extensions += ['rst2pdf.pdfbuilder']
+except ImportError:
+    pass
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'The Linux Kernel'
+copyright = '2016, The kernel development community'
+author = 'The kernel development community'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# In a normal build, version and release are are set to KERNELVERSION and
+# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
+# arguments.
+#
+# The following code tries to extract the information by reading the Makefile,
+# when Sphinx is run directly (e.g. by Read the Docs).
+try:
+    makefile_version = None
+    makefile_patchlevel = None
+    for line in open('../Makefile'):
+        key, val = [x.strip() for x in line.split('=', 2)]
+        if key == 'VERSION':
+            makefile_version = val
+        elif key == 'PATCHLEVEL':
+            makefile_patchlevel = val
+        if makefile_version and makefile_patchlevel:
+            break
+except:
+    pass
+finally:
+    if makefile_version and makefile_patchlevel:
+        version = release = makefile_version + '.' + makefile_patchlevel
+    else:
+        sys.stderr.write('Warning: Could not extract kernel version\n')
+        version = release = "unknown version"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['output']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+primary_domain = 'C'
+highlight_language = 'C'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+# The Read the Docs theme is available from
+# - https://github.com/snide/sphinx_rtd_theme
+# - https://pypi.python.org/pypi/sphinx_rtd_theme
+# - python-sphinx-rtd-theme package (on Debian)
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+except ImportError:
+    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TheLinuxKerneldoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation',
+     'The kernel development community', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
+     author, 'TheLinuxKernel', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = project
+
+# The HTML theme for the epub output. Since the default themes are not
+# optimized for small screen space, using the same theme for HTML and epub
+# output is usually not wise. This defaults to 'epub', a theme designed to save
+# visual space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or 'en' if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files that should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the Pillow.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
+
+#=======
+# rst2pdf
+#
+# Grouping the document tree into PDF files. List of tuples
+# (source start file, target name, title, author, options).
+#
+# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
+#
+# FIXME: Do not add the index file here; the result will be too big. Adding
+# multiple PDF files here actually tries to get the cross-referencing right
+# *between* PDF files.
+pdf_documents = [
+    ('index', u'Kernel', u'Kernel', u'J. Random Bozo'),
+]
+
+# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
+# the Docs). In a normal build, these are supplied from the Makefile via command
+# line arguments.
+kerneldoc_bin = '../scripts/kernel-doc'
+kerneldoc_srctree = '..'
diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt
index 122b7f4876bb..91ce82d5f0c4 100644
--- a/Documentation/dmaengine/provider.txt
+++ b/Documentation/dmaengine/provider.txt
@@ -323,7 +323,7 @@ supported.
    * device_resume
      - Resumes a transfer on the channel
      - This command should operate synchronously on the channel,
-       pausing right away the work of the given channel
+       resuming right away the work of the given channel
 
    * device_terminate_all
      - Aborts all the pending and ongoing transfers on the channel
diff --git a/Documentation/index.rst b/Documentation/index.rst
new file mode 100644
index 000000000000..71a276f34c7f
--- /dev/null
+++ b/Documentation/index.rst
@@ -0,0 +1,23 @@
+.. The Linux Kernel documentation master file, created by
+   sphinx-quickstart on Fri Feb 12 13:51:46 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to The Linux Kernel's documentation!
+============================================
+
+Nothing for you to see here *yet*. Please move along.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 82b42c958d1c..a2a662d4da83 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -3992,8 +3992,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 
         trace_event=[event-list]
                         [FTRACE] Set and start specified trace events in order
-                        to facilitate early boot debugging.
-                        See also Documentation/trace/events.txt
+                        to facilitate early boot debugging. The event-list is a
+                        comma separated list of trace events to enable. See
+                        also Documentation/trace/events.txt
 
         trace_options=[option-list]
                         [FTRACE] Enable or disable tracer options at boot.
diff --git a/Documentation/mic/mpssd/mpssd.c b/Documentation/mic/mpssd/mpssd.c
index 30fb842a976d..49db1def1721 100644
--- a/Documentation/mic/mpssd/mpssd.c
+++ b/Documentation/mic/mpssd/mpssd.c
@@ -1538,9 +1538,9 @@ set_cmdline(struct mic_info *mic)
 
         len = snprintf(buffer, PATH_MAX,
                 "clocksource=tsc highres=off nohz=off ");
-        len += snprintf(buffer + len, PATH_MAX,
+        len += snprintf(buffer + len, PATH_MAX - len,
                 "cpufreq_on;corec6_off;pc3_off;pc6_off ");
-        len += snprintf(buffer + len, PATH_MAX,
+        len += snprintf(buffer + len, PATH_MAX - len,
                 "ifcfg=static;address,172.31.%d.1;netmask,255.255.255.0",
                 mic->id + 1);
 
diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.txt
index babd6378ec05..3010576c9fca 100644
--- a/Documentation/security/self-protection.txt
+++ b/Documentation/security/self-protection.txt
@@ -183,8 +183,9 @@ provide meaningful defenses.
 ### Canaries, blinding, and other secrets
 
 It should be noted that things like the stack canary discussed earlier
-are technically statistical defenses, since they rely on a (leakable)
-secret value.
+are technically statistical defenses, since they rely on a secret value,
+and such values may become discoverable through an information exposure
+flaw.
 
 Blinding literal values for things like JITs, where the executable
 contents may be partially under the control of userspace, need a similar
@@ -199,8 +200,8 @@ working?) in order to maximize their success.
 Since the location of kernel memory is almost always instrumental in
 mounting a successful attack, making the location non-deterministic
 raises the difficulty of an exploit. (Note that this in turn makes
-the value of leaks higher, since they may be used to discover desired
-memory locations.)
+the value of information exposures higher, since they may be used to
+discover desired memory locations.)
 
 #### Text and module base
 
@@ -222,14 +223,21 @@ become more difficult to locate.
 Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up
 being relatively deterministic in layout due to the order of early-boot
 initializations. If the base address of these areas is not the same
-between boots, targeting them is frustrated, requiring a leak specific
-to the region.
+between boots, targeting them is frustrated, requiring an information
+exposure specific to the region.
+
+#### Structure layout
+
+By performing a per-build randomization of the layout of sensitive
+structures, attacks must either be tuned to known kernel builds or expose
+enough kernel memory to determine structure layouts before manipulating
+them.
 
 
-## Preventing Leaks
+## Preventing Information Exposures
 
 Since the locations of sensitive structures are the primary target for
-attacks, it is important to defend against leaks of both kernel memory
+attacks, it is important to defend against exposure of both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
@@ -250,8 +258,8 @@ sure structure holes are cleared.
 When releasing memory, it is best to poison the contents (clear stack on
 syscall return, wipe heap memory on a free), to avoid reuse attacks that
 rely on the old contents of memory. This frustrates many uninitialized
-variable attacks, stack info leaks, heap info leaks, and use-after-free
-attacks.
+variable attacks, stack content exposures, heap content exposures, and
+use-after-free attacks.
 
 ### Destination tracking
 
diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed
new file mode 100644
index 000000000000..c1503fcca4ec
--- /dev/null
+++ b/Documentation/sphinx/convert_template.sed
@@ -0,0 +1,18 @@
+#
+# Pandoc doesn't grok <function> or <structname>, so convert them
+# ahead of time.
+#
+# Use the following escapes to pass through pandoc:
+#       $bq = "`"
+#       $lt = "<"
+#       $gt = ">"
+#
+s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1()$bq%g
+s%<function>\([^<(]\+\)</function>%:c:func:$bq\1()$bq%g
+s%<structname>struct *\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
+s%struct <structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
+s%<structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
+#
+# Wrap docproc directives in para and code blocks.
+#
+s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%
diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py
new file mode 100644
index 000000000000..4adfb0e91ecc
--- /dev/null
+++ b/Documentation/sphinx/kernel-doc.py
@@ -0,0 +1,127 @@
+# coding=utf-8
+#
+# Copyright © 2016 Intel Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+# Authors:
+#    Jani Nikula <jani.nikula@intel.com>
+#
+# Please make sure this works on both python2 and python3.
+#
+
+import os
+import subprocess
+import sys
+import re
+
+from docutils import nodes, statemachine
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives
+from sphinx.util.compat import Directive
+
+class KernelDocDirective(Directive):
+    """Extract kernel-doc comments from the specified file"""
+    required_argument = 1
+    optional_arguments = 4
+    option_spec = {
+        'doc': directives.unchanged_required,
+        'functions': directives.unchanged_required,
+        'export': directives.flag,
+        'internal': directives.flag,
+    }
+    has_content = False
+
+    def run(self):
+        env = self.state.document.settings.env
+        cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
+
+        filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
+
+        # Tell sphinx of the dependency
+        env.note_dependency(os.path.abspath(filename))
+
+        tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
+        source = filename
+
+        # FIXME: make this nicer and more robust against errors
+        if 'export' in self.options:
+            cmd += ['-export']
+        elif 'internal' in self.options:
+            cmd += ['-internal']
+        elif 'doc' in self.options:
+            cmd += ['-function', str(self.options.get('doc'))]
+        elif 'functions' in self.options:
+            for f in str(self.options.get('functions')).split(' '):
+                cmd += ['-function', f]
+
+        cmd += [filename]
+
+        try:
+            env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
+
+            p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
+            out, err = p.communicate()
+
+            # python2 needs conversion to unicode.
+            # python3 with universal_newlines=True returns strings.
+            if sys.version_info.major < 3:
+                out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
+
+            if p.returncode != 0:
+                sys.stderr.write(err)
+
+                env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
+                return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
+            elif env.config.kerneldoc_verbosity > 0:
+                sys.stderr.write(err)
+
+            lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
+            result = ViewList()
+
+            lineoffset = 0;
+            line_regex = re.compile("^#define LINENO ([0-9]+)$")
+            for line in lines:
+                match = line_regex.search(line)
+                if match:
+                    # sphinx counts lines from 0
+                    lineoffset = int(match.group(1)) - 1
+                    # we must eat our comments since the upset the markup
+                else:
+                    result.append(line, source, lineoffset)
+                    lineoffset += 1
+
+            node = nodes.section()
+            node.document = self.state.document
+            self.state.nested_parse(result, self.content_offset, node)
+
+            return node.children
+
+        except Exception as e:
+            env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
+                         (" ".join(cmd), str(e)))
+            return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
+
+def setup(app):
+    app.add_config_value('kerneldoc_bin', None, 'env')
+    app.add_config_value('kerneldoc_srctree', None, 'env')
+    app.add_config_value('kerneldoc_verbosity', 1, 'env')
+
+    app.add_directive('kernel-doc', KernelDocDirective)
diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed
new file mode 100644
index 000000000000..392770bac53b
--- /dev/null
+++ b/Documentation/sphinx/post_convert.sed
@@ -0,0 +1,23 @@
+#
+# Unescape.
+#
+s/$bq/`/g
+s/$lt/</g
+s/$gt/>/g
+#
+# pandoc thinks that both "_" needs to be escaped.  Remove the extra
+# backslashes.
+#
+s/\\_/_/g
+#
+# Unwrap docproc directives.
+#
+s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n   :export:/
+s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n   :internal:/
+s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :functions: \2/
+s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :doc: \2/
+s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
+#
+# Trim trailing whitespace.
+#
+s/[[:space:]]*$//
diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
new file mode 100755
index 000000000000..909a73065e0a
--- /dev/null
+++ b/Documentation/sphinx/tmplcvt
@@ -0,0 +1,19 @@
+#!/bin/bash
+#
+# Convert a template file into something like RST
+#
+# fix <function>
+# feed to pandoc
+# fix \_
+# title line?
+#
+
+in=$1
+rst=$2
+tmp=$rst.tmp
+
+cp $in $tmp
+sed --in-place -f convert_template.sed $tmp
+pandoc -s -S -f docbook -t rst -o $rst $tmp
+sed --in-place -f post_convert.sed $rst
+rm $tmp
diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt
index eaf8297dbca2..e8e2ebafe5fa 100644
--- a/Documentation/sync_file.txt
+++ b/Documentation/sync_file.txt
@@ -6,8 +6,8 @@
 
 This document serves as a guide for device drivers writers on what the
 sync_file API is, and how drivers can support it. Sync file is the carrier of
-the fences(struct fence) that needs to synchronized between drivers or across
-process boundaries.
+the fences(struct fence) that are needed to synchronize between drivers or
+across process boundaries.
 
 The sync_file API is meant to be used to send and receive fence information
 to/from userspace. It enables userspace to do explicit fencing, where instead
@@ -32,7 +32,7 @@ in-fences and out-fences
 Sync files can go either to or from userspace. When a sync_file is sent from
 the driver to userspace we call the fences it contains 'out-fences'. They are
 related to a buffer that the driver is processing or is going to process, so
-the driver an create out-fence to be able to notify, through fence_signal(),
+the driver creates an out-fence to be able to notify, through fence_signal(),
 when it has finished using (or processing) that buffer. Out-fences are fences
 that the driver creates.
 
diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle
index 654afd72eb24..bbb9d6ae05ca 100644
--- a/Documentation/zh_CN/CodingStyle
+++ b/Documentation/zh_CN/CodingStyle
@@ -24,34 +24,33 @@ Documentation/CodingStyle的中文翻译
 
                 Linux内核代�风格
 
-这是一个简短的文档，�述了linux内核的首选代�风格。代�风格是因人而异的，而且我
-�愿�把我的观点强加给任何人，�过这里所讲述的是我必须�维护的代�所�守的风格，
-并且我也希望�大多数其他代�也能�守这个风格。请在写代�时至少考虑一下本文所述的
-风格。
+这是一个简短的文档，�述了 linux 内核的首选代�风格。代�风格是因人而异的，而且我
+�愿�把自己的观点强加给任何人，但这就�我去�任何事情都必须�循的原则那样，我也
+希望在�大多数事上��这�的�度。请（在写代�时）至少考虑一下这里的代�风格。
 
-首先，我建议你打�一份GNU代�规范，然���读它。烧了它，这是一个具有�大象�性
-�义的动作。
+首先，我建议你打�一份 GNU 代�规范，然���读。烧了它，这是一个具有�大象�性�义
+的动作。
 
 �管怎样，现在我们开始：
 
 
-                第一章：缩进
+                第一章：缩进
 
-制表符是8个字符，所以缩进也是8个字符。有些异端�动试图将缩进�为4（乃至2）个字符
-深，这几乎相当于�试将圆周率的值定义为3。
+制表符是 8 个字符，所以缩进也是 8 个字符。有些异端�动试图将缩进�为 4（甚至 2�）
+个字符深，这几乎相当于�试将圆周率的值定义为 3。
 
 �由：缩进的全部�义就在于清楚的定义一个控制�起止于何处。尤其是当你盯�你的�幕
-连续看了20�时之�，你将会�现大一点的缩进会使你更容易分辨缩进。
+连续看了 20 �时之�，你将会�现大一点的缩进会使你更容易分辨缩进。
 
-现在，有些人会抱怨8个字符的缩进会使代���边移动的太远，在80个字符的终端�幕上
-就很难读这样的代�。这个问题的答案是，如果你需�3级以上的缩进，�管用何�方�你
+现在，有些人会抱怨 8 个字符的缩进会使代���边移动的太远，在 80 个字符的终端�幕上
+就很难读这样的代�。这个问题的答案是，如果你需� 3 级以上的缩进，�管用何�方�你
 的代�已�有问题了，应该修正你的程�。
 
-简而言之，8个字符的缩进�以让代�更容易阅读，还有一个好处是当你的函数嵌套太深的
+简而言之，8 个字符的缩进�以让代�更容易阅读，还有一个好处是当你的函数嵌套太深的
 时候�以给你警告。留心这个警告。
 
-在switch语�中消除多级缩进的首选的方�是让“switch�和从属于它的“case�标签对�于�
-一列，而��“两次缩进�“case�标签。比如：
+在 switch 语�中消除多级缩进的首选的方�是让 “switch� 和从属于它的 “case� 标签
+对�于�一列，而�� “两次缩进� “case� 标签。比如：
 
         switch (suffix) {
         case 'G':
@@ -70,7 +69,6 @@ Documentation/CodingStyle的中文翻译
                 break;
         }
 
-
 ��把多个语�放在一行里，除�你有什么东西���：
 
         if (condition) do_this;
@@ -79,7 +77,7 @@ Documentation/CodingStyle的中文翻译
 也��在一行里放多个赋值语�。内核代�风格超级简�。就是���能导致别人误读的表
 达�。
 
-除了注释�文档和Kconfig之外，��使用空格�缩进，��的例�是例外，是有�为之。
+除了注释�文档和 Kconfig 之外，��使用空格�缩进，��的例�是例外，是有�为之。
 
 选用一个好的编辑器，��在行尾留空格。
 
@@ -88,27 +86,18 @@ Documentation/CodingStyle的中文翻译
 
 代�风格的�义就在于使用平常使用的工具�维�代�的�读性和�维护性。
 
-�一行的长度的�制是80列，我们强烈建议您�守这个惯例。
+�一行的长度的�制是 80 列，我们强烈建议您�守这个惯例。
 
-长于80列的语��打散�有�义的片段。�个片段�明显短于原�的语�，而且放置的�置
-也明显的��。�样的规则也适用于有很长�数列表的函数头。长字符串也�打散�较短的
-字符串。唯一的例外是超过80列�以大幅度�高�读性并且�会��信�的情况。
-
-void fun(int a, int b, int c)
-{
-        if (condition)
-                printk(KERN_WARNING "Warning this is a long printk with "
-                                                "3 parameters a: %u b: %u "
-                                                "c: %u \n", a, b, c);
-        else
-                next_statement;
-}
+长于 80 列的语��打散�有�义的片段。除�超过 80 列能显著增加�读性，并且�会��
+信�。�片段�明显短于�片段，并明显��。这�样适用于有�很长�数列表的函数头。
+然而，�对��打散对用户��的字符串，例如 printk 信�，因为这将导致无法 grep 这些
+信�。
 
                 第三章：大括�和空格的放置
 
 C语言风格中�外一个常�问题是大括�的放置。和缩进大���，选择或弃用��放置策
-略并没有多少技术上的原因，�过首选的方�，就�Kernighan和Ritchie展示给我们的，是
-把起始大括�放在行尾，而把结�大括�放在行首，所以：
+略并没有多少技术上的原因，�过首选的方�，就� Kernighan 和 Ritchie 展示给我们的，
+是把起始大括�放在行尾，而把结�大括�放在行首，所以：
 
         if (x is true) {
                 we do y
@@ -134,12 +123,12 @@ C语言风格中å�¦å¤–一个常è§�问题是大括å�·çš„放置。和缩进大å°�ä
                 body of function
         }
 
-全世界的异端�能会抱怨这个�一致性是……呃……�一致的，�过所有�维�全的人都知�（
-a）K&R是_正确的_，并且（b）K&R是正确的。此外，�管怎样函数都是特殊的（在C语言中
-，函数是�能嵌套的）。
+全世界的异端�能会抱怨这个�一致性是……呃……�一致的，�过所有�维�全的人都知�
+(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，�管怎样函数都是特殊的（C
+函数是�能嵌套的）。
 
-注�结�大括�独自��一行，除�它��跟��一个语�的剩余部分，也就是do语�中的
-“while�或者if语�中的“else�，�这样：
+注�结�大括�独自��一行，除�它��跟��一个语�的剩余部分，也就是 do 语�中的
+“while� 或者 if 语�中的 “else�，�这样：
 
         do {
                 body of do-loop
@@ -158,41 +147,50 @@ a）K&R是_正确的_，并且（b）K&R是正确的。此外，ä¸�管怎样函æ
 �由：K&R。
 
 也请注�这�大括�的放置方�也能使空（或者差�多空的）行的数�最�化，�时�失�
-读性。因此，由于你的�幕上的新行是���生资�（想想25行的终端�幕），你将会有更
+读性。因此，由于你的�幕上的新行是���生资�（想想 25 行的终端�幕），你将会有更
 多的空行�放置注释。
 
 当�有一个�独的语�的时候，�用加�必�的大括�。
 
-if (condition)
-        action();
+        if (condition)
+                action();
+
+和
+
+        if (condition)
+                do_this();
+        else
+                do_that();
 
-这点�适用于本身为�个�件语�的一个分支的�独语�。这时需�在两个分支里都使用大
-括�。
+这并�适用于�有一个�件分支是�语�的情况；这时所有分支都�使用大括�：
 
-if (condition) {
-        do_this();
-        do_that();
-} else {
-        otherwise();
-}
+        if (condition) {
+                do_this();
+                do_that();
+        } else {
+                otherwise();
+        }
 
                 3.1：空格
 
-Linux内核的空格使用方�（主�）�决于它是用于函数还是关键字。（大多数）关键字�
-�加一个空格。值得注�的例外是sizeof�typeof�alignof和__attribute__，这些关键字
-�些程度上看起�更�函数（它们在Linux里也常常伴��括�而使用，尽管在C语言里这样
-的�括��是必需的，就�“struct fileinfo info�声明过�的“sizeof info�）。
+Linux 内核的空格使用方�（主�）�决于它是用于函数还是关键字。（大多数）关键字�
+�加一个空格。值得注�的例外是 sizeof�typeof�alignof 和 __attribute__，这些
+关键字�些程度上看起�更�函数（它们在 Linux 里也常常伴��括�而使用，尽管在 C 里
+这样的�括��是必需的，就� “struct fileinfo info� 声明过�的 “sizeof info�）。
 
 所以在这些关键字之�放一个空格：
+
         if, switch, case, for, do, while
-但是��在sizeof�typeof�alignof或者__attribute__这些关键字之�放空格。例如，
+
+但是��在 sizeof�typeof�alignof 或者 __attribute__ 这些关键字之�放空格。例如，
+
         s = sizeof(struct file);
 
 ��在�括�里的表达�两侧加空格。这是一个�例：
 
         s = sizeof( struct file );
 
-当声明指针类型或者返回指针类型的函数时，“*�的首选使用方�是使之�近���或者函
+当声明指针类型或者返回指针类型的函数时，“*� 的首选使用方�是使之�近���或者函
 数�，而�是�近类型�。例�：
 
         char *linux_banner;
@@ -204,15 +202,18 @@ Linux内核的空格使用方�（主�）�决于它是用于函数还是关
         =  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
 
 但是一元�作符���加空格：
+
         &  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
 
 �缀自加和自�一元�作符��加空格：
+
         ++  --
 
 �缀自加和自�一元�作符��加空格：
+
         ++  --
 
-“.�和“->�结构体�员�作符���加空格。
+‘.’ 和 “->� 结构体�员�作符���加空格。
 
 ��在行尾留空白。有些�以自动缩进的编辑器会在新行的行首加入适�的空白，然�你
 就�以直接在那一行输入代�。�过�如你最�没有在那一行输入代�，有些编辑器就�
@@ -225,23 +226,23 @@ Linux内核的空格使用方�（主�）�决于它是用于函数还是关
 
                 第四章：命�
 
-C是一个简朴的语言，你的命�也应该这样。和Modula-2和Pascal程�员��，C程�员�使
-用类似ThisVariableIsATemporaryCounter这样�丽的�字。C程�员会称那个��为“tmp�
-，这样写起�会更容易，而且至少�会令其难于�解。
+C是一个简朴的语言，你的命�也应该这样。和 Modula-2 和 Pascal 程�员��，C 程�员
+�使用类似 ThisVariableIsATemporaryCounter 这样�丽的�字。C 程�员会称那个��
+为 “tmp�，这样写起�会更容易，而且至少�会令其难于�解。
 
 �过，虽然混用大�写的�字是��倡使用的，但是全局��还是需�一个具�述性的�字
-。称一个全局函数为“foo�是一个难以饶�的错误。
+。称一个全局函数为 “foo� 是一个难以饶�的错误。
 
 全局��（�有当你真正需�它们的时候�用它）需�有一个具�述性的�字，就�全局函
-数。如果你有一个�以计算活动用户数�的函数，你应该�它“count_active_users()�或者
-类似的�字，你�应该�它“cntuser()�。
+数。如果你有一个�以计算活动用户数�的函数，你应该�它 “count_active_users()�
+或者类似的�字，你�应该�它 “cntuser()�。
 
 在函数�中包�函数类型（所谓的匈牙利命�法）是脑�出了问题——编译器知�那些类型而
 且能够检查那些类型，这样��能把程�员弄糊涂了。难怪微软总是制造出有问题的程�。
 
 本地���应该简短，而且能够表达相关的�义。如果你有一些�机的整数型的循环计数器
-，它应该被称为“i�。�它“loop_counter�并无益处，如果它没有被误解的�能的�。类似
-的，“tmp��以用�称呼任�类型的临时��。
+，它应该被称为 “i�。�它 “loop_counter� 并无益处，如果它没有被误解的�能的�。
+类似的，“tmp� �以用�称呼任�类型的临时��。
 
 如果你怕混淆了你的本地���，你就�到�一个问题了，��函数增长�尔蒙失衡综�症
 。请看第六章（函数）。
@@ -249,9 +250,9 @@ C是一个简朴的语言，你的命å��也应该这样。和Modula-2å’ŒPascalç¨
 
                 第五章：Typedef
 
-��使用类似“vps_t�之类的东西。
+��使用类似 “vps_t� 之类的东西。
 
-对结构体和指针使用typedef是一个错误。当你在代�里看到：
+对结构体和指针使用 typedef 是一个错误。当你在代�里看到：
 
         vps_t a;
 
@@ -261,91 +262,91 @@ C是一个简朴的语言，你的命å��也应该这样。和Modula-2å’ŒPascalç¨
 
         struct virtual_container *a;
 
-你就知�“a�是什么了。
+你就知� “a� 是什么了。
 
-很多人认为typedef“能�高�读性�。实际�是这样的。它们�在下列情况下有用：
+很多人认为 typedef “能�高�读性�。实际�是这样的。它们�在下列情况下有用：
 
- (a) 完全��明的对象（这�情况下�主动使用typedef���这个对象实际上是什么）。
+ (a) 完全��明的对象（这�情况下�主动使用 typedef ���这个对象实际上是什么）。
 
-     例如：“pte_t�等��明对象，你�能用�适的访问函数�访问它们。
+     例如：“pte_t� 等��明对象，你�能用�适的访问函数�访问它们。
 
-     注����明性和“访问函数�本身是�好的。我们使用pte_t等类型的原因在于真的是
+     注����明性和“访问函数�本身是�好的。我们使用 pte_t 等类型的原因在于真的是
      完全没有任何共用的�访问信�。
 
- (b) 清楚的整数类型，如此，这层抽象就�以帮助消除到底是“int�还是“long�的混淆。
+ (b) 清楚的整数类型，如此，这层抽象就�以帮助消除到底是 “int� 还是 “long� 的混淆。
 
-     u8/u16/u32是完全没有问题的typedef，�过它们更符�类别(d)而�是这里。
+     u8/u16/u32 是完全没有问题的 typedef，�过它们更符�类别 (d) 而�是这里。
 
-     �次注���这样�，必须事出有因。如果�个��是“unsigned long“，那么没有必�
+     �次注���这样�，必须事出有因。如果�个��是 “unsigned long“，那么没有必�
 
         typedef unsigned long myflags_t;
 
-     �过如果有一个明确的原因，比如它在��情况下�能会是一个“unsigned int�而在
-     其他情况下�能为“unsigned long�，那么就��犹豫，请务必使用typedef。
+     �过如果有一个明确的原因，比如它在��情况下�能会是一个 “unsigned int� 而在
+     其他情况下�能为 “unsigned long�，那么就��犹豫，请务必使用 typedef。
 
  (c) 当你使用sparse按字�的创建一个新类型��类型检查的时候。
 
  (d) 和标准C99类型相�的类型，在�些例外的情况下。
 
-     虽然让眼�和脑筋�适应新的标准类型比如“uint32_t��需�花很多时间，�是有些
+     虽然让眼�和脑筋�适应新的标准类型比如 “uint32_t� �需�花很多时间，�是有些
      人�然拒�使用它们。
 
-     因此，Linux特有的等�于标准类型的“u8/u16/u32/u64�类型和它们的有符�类型是被
+     因此，Linux 特有的等�于标准类型的 “u8/u16/u32/u64� 类型和它们的有符�类型是被
      �许的——尽管在你自己的新代�中，它们�是强制�求�使用的。
 
      当编辑已�使用了�个类型集的已有代�时，你应该�循那些代�中已��出的选择。
 
  (e) �以在用户空间安全使用的类型。
 
-     在�些用户空间��的结构体里，我们�能�求C99类型而且�能用上��到的“u32�
-     类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。
+     在�些用户空间��的结构体里，我们�能�求C99类型而且�能用上��到的 “u32�
+     类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。
 
-�能还有其他的情况，�过基本的规则是永远��使用typedef，除�你�以明确的应用上
+�能还有其他的情况，�过基本的规则是永远��使用 typedef，除�你�以明确的应用上
 述�个规则中的一个。
 
 总的�说，如果一个指针或者一个结构体里的元素�以��的被直接访问到，那么它们就�
-应该是一个typedef。
+应该是一个 typedef。
 
 
                 第六章：函数
 
 函数应该简短而漂亮，并且�完�一件事情。函数应该�以一�或者两�显示完（我们都知
-�ISO/ANSI�幕大�是80x24），��一件事情，而且把它�好。
+� ISO/ANSI �幕大�是 80x24），��一件事情，而且把它�好。
 
 一个函数的最大长度是和该函数的��度和缩进级数��比的。所以，如果你有一个�论上
-很简�的�有一个很长（但是简�）的case语�的函数，而且你需�在�个case里�很多很
-�的事情，这样的函数尽管很长，但也是�以的。
+很简�的�有一个很长（但是简�）的 case 语�的函数，而且你需�在�个 case 里�
+很多很�的事情，这样的函数尽管很长，但也是�以的。
 
 �过，如果你有一个��的函数，而且你怀疑一个天分�是很高的高中一年级学生�能甚至
 ��清楚这个函数的目的，你应该严格的�守���到的长度�制。使用辅助函数，并为之
 �个具�述性的�字（如果你觉得它们的性能很��的�，�以让编译器内�它们，这样的
 效果往往会比你写一个��函数的效果�好。）
 
-函数的�外一个衡�标准是本地��的数�。此数��应超过5�10个，�则你的函数就有
+函数的�外一个衡�标准是本地��的数�。此数��应超过 5�10 个，�则你的函数就有
 问题了。�新考虑一下你的函数，把它分拆�更�的函数。人的大脑一般�以轻�的�时跟
-踪7个��的事物，如果�增多的�，就会糊涂了。�便你�颖过人，你也�能会记�清你2
-个星期��过的事情。
+踪 7 个��的事物，如果�增多的�，就会糊涂了。�便你�颖过人，你也�能会记�清你
+2 个星期��过的事情。
 
-在�文件里，使用空行隔开��的函数。如果该函数需�被导出，它的EXPORT*�应该紧贴
+在�文件里，使用空行隔开��的函数。如果该函数需�被导出，它的 EXPORT* �应该紧贴
 在它的结�大括�之下。比如：
 
-int system_is_up(void)
-{
-        return system_state == SYSTEM_RUNNING;
-}
-EXPORT_SYMBOL(system_is_up);
+        int system_is_up(void)
+        {
+                return system_state == SYSTEM_RUNNING;
+        }
+        EXPORT_SYMBOL(system_is_up);
 
-在函数原型中，包�函数�和它们的数�类型。虽然C语言里没有这样的�求，在Linux里这
+在函数原型中，包�函数�和它们的数�类型。虽然C语言里没有这样的�求，在 Linux 里这
 是�倡的�法，因为这样�以很简�的给读者�供更多的有价值的信�。
 
 
                 第七章：集中的函数退出途径
 
-虽然被�些人声称已�过时，但是goto语�的等价物还是�常被编译器所使用，具体形�是
+虽然被�些人声称已�过时，但是 goto 语�的等价物还是�常被编译器所使用，具体形�是
 无�件跳转指令。
 
-当一个函数从多个�置退出并且需��一些通用的清�工作的时候，goto的好处就显现出�
-了。
+当一个函数从多个�置退出，并且需��一些类似清�的常��作时，goto 语�就很方便了。
+如果并�需�清��作，那么直接 return ��。
 
 �由是：
 
@@ -354,26 +355,37 @@ EXPORT_SYMBOL(system_is_up);
 - �以��由于修改时忘记更新�个�独的退出点而导致的错误
 - �轻了编译器的工作，无需删除冗余代�;)
 
-int fun(int a)
-{
-        int result = 0;
-        char *buffer = kmalloc(SIZE);
-
-        if (buffer == NULL)
-                return -ENOMEM;
-
-        if (condition1) {
-                while (loop1) {
-                        ...
+        int fun(int a)
+        {
+                int result = 0;
+                char *buffer;
+
+                buffer = kmalloc(SIZE, GFP_KERNEL);
+                if (!buffer)
+                        return -ENOMEM;
+
+                if (condition1) {
+                        while (loop1) {
+                                ...
+                        }
+                        result = 1;
+                        goto out_buffer;
                 }
-                result = 1;
-                goto out;
+                ...
+        out_buffer:
+                kfree(buffer);
+                return result;
         }
-        ...
-out:
-        kfree(buffer);
-        return result;
-}
+
+一个需�注�的常�错误是“一个 err 错误�，就�这样：
+
+        err:
+                kfree(foo->bar);
+                kfree(foo);
+                return ret;
+
+这段代�的错误是，在�些退出路径上 “foo� 是 NULL。通常情况下，通过把它分离�两个
+错误标签 “err_bar:� 和 “err_foo:� �修�这个错误。
 
                 第八章：注释
 
@@ -386,10 +398,10 @@ out:
 加太多。你应该�的，是把注释放在函数的头部，告诉人们它�了什么，也�以加上它�这
 些事情的原因。
 
-当注释内核API函数时，请使用kernel-doc格�。请看
-Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信�。
+当注释内核API函数时，请使用 kernel-doc 格�。请看
+Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc 以获得详细信�。
 
-Linux的注释风格是C89“/* ... */�风格。��使用C99风格“// ...�注释。
+Linux的注释风格是 C89 “/* ... */� 风格。��使用 C99 风格 “// ...� 注释。
 
 长（多行）的首选注释风格是：
 
@@ -402,6 +414,15 @@ Linux的注释风格是C89“/* ... */�风格。��使用C99风格“// ...
          * with beginning and ending almost-blank lines.
          */
 
+对于在 net/ 和 drivers/net/ 的文件，首选的长（多行）注释风格有些��。
+
+        /* The preferred comment style for files in net/ and drivers/net
+         * looks like this.
+         *
+         * It is nearly the same as the generally preferred comment style,
+         * but there is no initial almost-blank line.
+         */
+
 注释数�也是很��的，�管是基本类型还是�生类型。为了方便实现这一点，�一行应�
 声明一个数�（��使用逗��一次声明多个数�）。这样你就有空间�为�个数�写一段
 �注释�解释它们的用途了。
@@ -409,49 +430,63 @@ Linux的注释风格是C89“/* ... */�风格。��使用C99风格“// ...
 
                 第�章：你已�把事情弄糟了
 
-这没什么，我们都是这样。�能你的使用了很长时间Unix的朋�已�告诉你“GNU emacs�能
-自动帮你格�化C�代�，而且你也注�到了，确实是这样，�过它所使用的默认值和我们
-想�的相去甚远（实际上，甚至比�机打的还�差——无数个猴�在GNU emacs里打字永远�
-会创造出一个好程�）（译注：请�考Infinite Monkey Theorem）
-
-所以你�么放弃GNU emacs，�么改�它让它使用更��的设定。�采用�一个方案，你�
-以把下�这段粘贴到你的.emacs文件里。
-
-(defun linux-c-mode ()
-  "C mode with adjusted defaults for use with the Linux kernel."
-  (interactive)
-  (c-mode)
-  (c-set-style "K&R")
-  (setq tab-width 8)
-  (setq indent-tabs-mode t)
-  (setq c-basic-offset 8))
-
-这样就定义了M-x linux-c-mode命令。当你hack一个模�的时候，如果你把字符串
--*- linux-c -*-放在头两行的�个�置，这个模�将会被自动调用。如果你希望在你修改
-/usr/src/linux里的文件时魔术般自动打开linux-c-mode的�，你也�能需�添加
-
-(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
-                        auto-mode-alist))
-
-到你的.emacs文件里。
-
-�过就算你�试让emacs正确的格�化代�失败了，也并��味�你失去了一切：还�以用“
-indent�。
-
-�过，GNU indent也有和GNU emacs一样有问题的设定，所以你需�给它一些命令选项。�
-过，这还�算太糟糕，因为就算是GNU indent的作者也认�K&R的��性（GNU的人并�是�
-人，他们�是在这个问题上被严�的误导了），所以你��给indent指定选项“-kr -i8�
-（代表“K&R，8个字符缩进�），或者使用“scripts/Lindent�，这样就�以以最时髦的方�
+这没什么，我们都是这样。�能你的使用了很长时间 Unix 的朋�已�告诉你 “GNU emacs� 能
+自动帮你格�化 C �代�，而且你也注�到了，确实是这样，�过它所使用的默认值和我们
+想�的相去甚远（实际上，甚至比�机打的还�差——无数个猴�在 GNU emacs 里打字永远�
+会创造出一个好程�）（译注：请�考 Infinite Monkey Theorem）
+
+所以你�么放弃 GNU emacs，�么改�它让它使用更��的设定。�采用�一个方案，你�
+以把下�这段粘贴到你的 .emacs 文件里。
+
+(defun c-lineup-arglist-tabs-only (ignored)
+  "Line up argument lists by tabs, not spaces"
+  (let* ((anchor (c-langelem-pos c-syntactic-element))
+         (column (c-langelem-2nd-pos c-syntactic-element))
+         (offset (- (1+ column) anchor))
+         (steps (floor offset c-basic-offset)))
+    (* (max steps 1)
+       c-basic-offset)))
+
+(add-hook 'c-mode-common-hook
+          (lambda ()
+            ;; Add kernel style
+            (c-add-style
+             "linux-tabs-only"
+             '("linux" (c-offsets-alist
+                        (arglist-cont-nonempty
+                         c-lineup-gcc-asm-reg
+                         c-lineup-arglist-tabs-only))))))
+
+(add-hook 'c-mode-hook
+          (lambda ()
+            (let ((filename (buffer-file-name)))
+              ;; Enable kernel mode for the appropriate files
+              (when (and filename
+                         (string-match (expand-file-name "~/src/linux-trees")
+                                       filename))
+                (setq indent-tabs-mode t)
+                (setq show-trailing-whitespace t)
+                (c-set-style "linux-tabs-only")))))
+
+这会让 emacs 在 ~/src/linux-trees 目录下的 C �文件获得更好的内核代�风格。
+
+�过就算你�试让 emacs 正确的格�化代�失败了，也并��味�你失去了一切：还�以用
+“indent�。
+
+�过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需�给它一些命令选项。�
+过，这还�算太糟糕，因为就算是 GNU indent 的作者也认� K&R 的��性（GNU 的人并�是
+�人，他们�是在这个问题上被严�的误导了），所以你��给 indent 指定选项 “-kr -i8�
+（代表 “K&R，8 个字符缩进�），或者使用 “scripts/Lindent�，这样就�以以最时髦的方�
 缩进�代�。
 
-“indent�有很多选项，特别是�新格�化注释的时候，你�能需�看一下它的手册页。�过
-记�：“indent��能修正�的编程习惯。
+“indent� 有很多选项，特别是�新格�化注释的时候，你�能需�看一下它的手册页。�过
+记�：“indent� �能修正�的编程习惯。
 
 
-                第�章：Kconfig�置文件
+                第�章：Kconfig �置文件
 
-对于�布��树的所有Kconfig*�置文件�说，它们缩进方�与C代�相比有所��。紧挨
-在“config�定义下�的行缩进一个制表符，帮助信�则�多缩进2个空格。比如：
+对于�布��树的所有 Kconfig* �置文件�说，它们缩进方�与 C 代�相比有所��。紧挨
+在 “config� 定义下�的行缩进一个制表符，帮助信�则�多缩进 2 个空格。比如：
 
 config AUDIT
         bool "Auditing support"
@@ -470,7 +505,7 @@ config ADFS_FS_RW
         depends on ADFS_FS
         ...
 
-�查看�置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。
+�查看�置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
 
 
                 第�一章：数�结构
@@ -489,11 +524,11 @@ config ADFS_FS_RW
 很多数�结构实际上有2级引用计数，它们通常有��“类�的用户。�类计数器统计�类用
 户的数�，�当�类计数器�至零时，全局计数器�一。
 
-这�“多级引用计数�的例��以在内存管�（“struct mm_struct�：mm_users和mm_count）
+这�“多级引用计数�的例��以在内存管�（“struct mm_struct�：mm_users 和 mm_count）
 和文件系统（“struct super_block�：s_count和s_active）中找到。
 
 记�：如果�一个执行线索�以找到你的数�结构，但是这个数�结构没有引用计数器，这
-里几乎肯定是一个bug。
+里几乎肯定是一个 bug。
 
 
                 第�二章：�，枚举和RTL
@@ -508,102 +543,128 @@ config ADFS_FS_RW
 
 一般的，如果能写�内�函数就��写��函数的�。
 
-�有多个语�的�应该被包�在一个do-while代��里：
+�有多个语�的�应该被包�在一个 do-while 代��里：
 
-#define macrofun(a, b, c)                       \
-        do {                                    \
-                if (a == 5)                     \
-                        do_this(b, c);          \
-        } while (0)
+        #define macrofun(a, b, c)                       \
+                do {                                    \
+                        if (a == 5)                     \
+                                do_this(b, c);          \
+                } while (0)
 
 使用�的时候应��的事情：
 
 1) 影�控制�程的�：
 
-#define FOO(x)                                  \
-        do {                                    \
-                if (blah(x) < 0)                \
-                        return -EBUGGERED;      \
-        } while(0)
+        #define FOO(x)                                  \
+                do {                                    \
+                        if (blah(x) < 0)                \
+                                return -EBUGGERED;      \
+                } while (0)
 
 �常�好。它看起��一个函数，�过�能导致“调用�它的函数退出；��打乱读者大脑里
 的语法分�器。
 
 2) �赖于一个固定�字的本地��的�：
 
-#define FOO(val) bar(index, val)
+        #define FOO(val) bar(index, val)
 
 �能看起��是个�错的东西，�过它�常容易把读代�的人�糊涂，而且容易导致看起�
 �相关的改动带�错误。
 
-3) 作为左值的带�数的�： FOO(x) = y；如果有人把FOO��一个内�函数的�，这�用
+3) 作为左值的带�数的�： FOO(x) = y；如果有人把 FOO ��一个内�函数的�，这�用
 法就会出错了。
 
 4) 忘记了优先级：使用表达�定义常�的�必须将表达�置于一对�括�之内。带�数的
 �也�注�此类问题。
 
-#define CONSTANT 0x4000
-#define CONSTEXP (CONSTANT | 3)
+        #define CONSTANT 0x4000
+        #define CONSTEXP (CONSTANT | 3)
+
+5) 在�里定义类似函数的本地��时命�冲�：
 
-cpp手册对�的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register
+        #define FOO(x)                          \
+        ({                                      \
+                typeof(x) ret;                  \
+                ret = calc_ret(x);              \
+                (ret);                          \
+        })
+
+ret 是本地��的通用�字 - __foo_ret 更�容易与一个已存在的��冲�。
+
+cpp 手册对�的讲解很详细。gcc internals 手册也详细讲解了 RTL（译注：register
 transfer language），内核里的汇编语言�常用到它。
 
 
                 第�三章：打�内核消�
 
 内核开�者应该是�过良好教育的。请一定注�内核信�的拼写，以给人以好的�象。��
-用�规范的��比如“dont�，而�用“do not�或者“don't�。��这些信�简��明了�无
-歧义。
+用�规范的��比如 “dont�，而�用 “do not�或者 “don't�。��这些信�简��明了�
+无歧义。
 
 内核信��必以��（译注：英文��，�点）结�。
 
-在�括�里打�数字(%d)没有任何价值，应该��这样�。
+在�括�里打�数字 (%d) 没有任何价值，应该��这样�。
 
-<linux/device.h>里有一些驱动模型诊断�，你应该使用它们，以确�信�对应于正确的
-设备和驱动，并且被标记了正确的消�级别。这些�有：dev_err(), dev_warn(),
-dev_info()等等。对于那些�和�个特定设备相关连的信�，<linux/kernel.h>定义了
-pr_debug()和pr_info()。
+<linux/device.h> 里有一些驱动模型诊断�，你应该使用它们，以确�信�对应于正确的
+设备和驱动，并且被标记了正确的消�级别。这些�有：dev_err()，dev_warn()，
+dev_info() 等等。对于那些�和�个特定设备相关连的信�，<linux/printk.h> 定义了
+pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。
 
-写出好的调试信��以是一个很大的挑战；当你写出�之�，这些信�在远程除错的时候
-就会�为�大的帮助。当DEBUG符�没有被定义的时候，这些信��应该被编译进内核里
-（也就是说，默认地，它们�应该被包�在内）。如果你使用dev_dbg()或者pr_debug()，
-就能自动达到这个效果。很多�系统拥有Kconfig选项��用-DDEBUG。还有一个相关的惯例
-是使用VERBOSE_DEBUG�添加dev_vdbg()消�到那些已�由DEBUG�用的消�之上。
+写出好的调试信��以是一个很大的挑战；一旦你写出�，这些信�在远程除错时能�供�大
+的帮助。然而打�调试信�的处�方��打��调试信���。其他 pr_XXX() 函数能无�件地
+打�，pr_debug() ��；默认情况下它�会被编译，除�定义了 DEBUG 或设定了
+CONFIG_DYNAMIC_DEBUG。实际这�样是为了 dev_dbg()，一个相关约定是在一个已�开�了
+DEBUG 时，使用 VERBOSE_DEBUG �添加 dev_vdbg()。
+
+许多�系统拥有 Kconfig 调试选项�开� -DDEBUG 在对应的 Makefile 里�；在其他
+情况下，特殊文件使用 #define DEBUG。当一�调试信�需�被无�件打�时，例如，如果
+已�包�一个调试相关的 #ifdef �件，printk(KERN_DEBUG ...) 就�被使用。
 
 
                 第�四章：分�内存
 
-内核�供了下�的一般用途的内存分�函数：kmalloc()，kzalloc()，kcalloc()和
-vmalloc()。请�考API文档以获�有关它们的详细信�。
+内核�供了下�的一般用途的内存分�函数：
+kmalloc()，kzalloc()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。
+请�考 API 文档以获�有关它们的详细信�。
 
 传递结构体大�的首选形�是这样的：
 
         p = kmalloc(sizeof(*p), ...);
 
-�外一�传递方�中，sizeof的�作数是结构体的�字，这样会�低�读性，并且�能会引
-入bug。有�能指针��类型被改�时，而对应的传递给内存分�函数的sizeof的结果��。
+�外一�传递方�中，sizeof 的�作数是结构体的�字，这样会�低�读性，并且�能会引
+入 bug。有�能指针��类型被改�时，而对应的传递给内存分�函数的 sizeof 的结果��。
 
-强制转�一个void指针返回值是多余的。C语言本身��了从void指针到其他任何指针类型
+强制转�一个 void 指针返回值是多余的。C 语言本身��了从 void 指针到其他任何指针类型
 的转�是没有问题的。
 
+分�一个数组的首选形�是这样的：
+
+        p = kmalloc_array(n, sizeof(...), ...);
+
+分�一个零长数组的首选形�是这样的：
+
+        p = kcalloc(n, sizeof(...), ...);
+
+两�形�检查分�大� n * sizeof(...) 的溢出，如果溢出返回 NULL。
+
 
                 第�五章：内�弊病
 
-有一个常�的误解是内�函数是gcc�供的�以让代��行更快的一个选项。虽然使用内�
+有一个常�的误解是内�函数是 gcc �供的�以让代��行更快的一个选项。虽然使用内�
 函数有时候是�当的（比如作为一�替代�的方�，请看第�二章），�过很多情况下�是
-这样。inline关键字的过度使用会使内核�大，从而使整个系统�行速度�慢。因为大内核
+这样。inline 关键字的过度使用会使内核�大，从而使整个系统�行速度�慢。因为大内核
 会�用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数�缓存分开的）而且会导
-致pagecache的�用内存�少。想象一下，一次pagecache未命中就会导致一次�盘寻�，将
-耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。
+致 pagecache 的�用内存�少。想象一下，一次pagecache未命中就会导致一次�盘寻�，
+将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
 
-一个基本的原则是如果一个函数有3行以上，就��把它��内�函数。这个原则的一个例
+一个基本的原则是如果一个函数有 3 行以上，就��把它��内�函数。这个原则的一个例
 外是，如果你知��个�数是一个编译时常�，而且因为这个常�你确定编译器在编译时能
-优化掉你的函数的大部分代�，那�然�以给它加上inline关键字。kmalloc()内�函数就
+优化掉你的函数的大部分代�，那�然�以给它加上 inline 关键字。kmalloc() 内�函数就
 是一个很好的例�。
 
-人们�常主张给static的而且�用了一次的函数加上inline，如此�会有任何�失，因为没
-有什么好�衡的。虽然从技术上说这是正确的，但是实际上这�情况下�使�加inline gcc
-也�以自动使其内�。而且其他用户�能会�求移除inline，由此而�的争论会抵消inline
+人们�常主张给 static 的而且�用了一次的函数加上 inline，如此�会有任何�失，因为没
+有什么好�衡的。虽然从技术上说这是正确的，但是实际上这�情况下�使�加 inline gcc
+也�以自动使其内�。而且其他用户�能会�求移除 inline，由此而�的争论会抵消 inline
 自身的潜在价值，得��失。
 
 
@@ -613,37 +674,37 @@ vmalloc()。请�考API文档以获�有关它们的详细信�。
 的一个值�以表示为一个错误代�整数（-Exxx�失败，0��功）或者一个“�功�布尔值（
 0�失败，�0��功）。
 
-混�使用这两�表达方�是难于�现的bug的��。如果C语言本身严格区分整形和布尔型�
-�，那么编译器就能够帮我们�现这些错误……�过C语言�区分。为了��产生这�bug，请
+混�使用这两�表达方�是难于�现的 bug 的��。如果 C 语言本身严格区分整形和布尔型�
+�，那么编译器就能够帮我们�现这些错误……�过 C 语言�区分。为了��产生这� bug，请
 �循下�的惯例：
 
         如果函数的�字是一个动作或者强制性的命令，那么这个函数应该返回错误代�整
         数。如果是一个判断，那么函数应该返回一个“�功�布尔值。
 
-比如，“add work�是一个命令，所以add_work()函数在�功时返回0，在失败时返回-EBUSY。
-类似的，因为“PCI device present�是一个判断，所以pci_dev_present()函数在�功找到
-一个匹�的设备时应该返回1，如果找�到时应该返回0。
+比如，“add work� 是一个命令，所以 add_work() 函数在�功时返回 0，在失败时返回 -EBUSY。
+类似的，因为 “PCI device present� 是一个判断，所以 pci_dev_present() 函数在�功找到
+一个匹�的设备时应该返回 1，如果找�到时应该返回 0。
 
 所有导出（译注：EXPORT）的函数都必须�守这个惯例，所有的公共函数也都应该如此。�
 有（static）函数�需�如此，但是我们也推�这样�。
 
 返回值是实际计算结果而�是计算是��功的标志的函数��此惯例的�制。一般的，他们
 通过返回一些正常值范围之外的结果�表示出错。典型的例�是返回指针的函数，他们使用
-NULL或者ERR_PTR机制�报告错误。
+NULL 或者 ERR_PTR 机制�报告错误。
 
 
                 第�七章：���新�明内核�
 
-头文件include/linux/kernel.h包�了一些�，你应该使用它们，而��自己写一些它们的
+头文件 include/linux/kernel.h 包�了一些�，你应该使用它们，而��自己写一些它们的
 ��。比如，如果你需�计算一个数组的长度，使用这个�
 
-  #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+        #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 
 类似的，如果你�计算�结构体�员的大�，使用
 
-  #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
+        #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
 
-还有�以�严格的类型检查的min()和max()�，如果你需��以使用它们。你�以自己看看
+还有�以�严格的类型检查的 min() 和 max() �，如果你需��以使用它们。你�以自己看看
 那个头文件里还定义了什么你�以拿�用的东西，如果有定义的�，你就�应在你的代�里
 自己�新定义。
 
@@ -653,42 +714,100 @@ NULL或者ERR_PTR机制�报告错误。
 有一些编辑器�以解释嵌入在�文件里的由一些特殊标记标明的�置信�。比如，emacs
 能够解释被标记�这样的行：
 
--*- mode: c -*-
+        -*- mode: c -*-
 
 或者这样的：
 
-/*
-Local Variables:
-compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
-End:
-*/
+        /*
+        Local Variables:
+        compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
+        End:
+        */
 
-Vim能够解释这样的标记：
+Vim 能够解释这样的标记：
 
-/* vim:set sw=8 noet */
+        /* vim:set sw=8 noet */
 
 ��在�代�中包�任何这样的内容。�个人都有他自己的编辑器�置，你的�文件�应
 该覆盖别人的�置。这包括有关缩进和模��置的标记。人们�以使用他们自己定制的模
 �，或者使用其他�以产生正确的缩进的巧妙方法。
 
 
+                第��章：内�汇编
+
+在特定架构的代�中，你也许需�内�汇编�使用 CPU 接�和平�相关功能。在需�
+这么�时，��犹豫。然而，当 C �以完�工作时，��无端地使用内�汇编。如果
+�能，你�以并且应该用 C 和硬件交互。
+
+考虑去写通用一点的内�汇编作为简明的辅助函数，而�是��写下它们的细节。记�
+内�汇编�以使用 C �数。
+
+大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编
+函数的 C 原型应该使用 “asmlinkage�。
+
+你�能需�将你的汇编语�标记为 volatile，�阻止 GCC 在没�现任何副作用�就
+移除了它。你�必总是这样�，虽然，这样�以�制�必�的优化。
+
+在写一个包�多�指令的�个内�汇编语�时，把��指令用引�字符串分离，并写在
+�独一行，在�个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下
+一�指令：
+
+        asm ("magic %reg1, #42\n\t"
+             "more_magic %reg2, %reg3"
+             : /* outputs */ : /* inputs */ : /* clobbers */);
+
+
+                第二�章：�件编译
+
+���能，就��在 .c 文件里�使用预处��件；这样�让代�更难阅读并且逻辑难以
+跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的�件表达�，�供空
+�作的桩版本（译注：桩程�，是指用�替�一部分功能的程�段）在 #else 情况下，
+�从 .c 文件中无�件地调用这些函数。编译器会��生�任何桩调用的代�，产生一致
+的结果，但逻辑将更加清晰。
+
+��编译整个函数，而�是部分函数或部分表达�。而�是在一个表达�添加 ifdef，
+解�部分或全部表达�到一个�独的辅助函数，并应用�件到该函数内。
+
+如果你有一个在特定�置中�能是未使用的函数或��，编译器将警告它定义了但未使用，
+标记这个定义为 __maybe_unused 而�是将它包�在一个预处��件中。（然而，如果
+一个函数或��总是未使用的，就直接删除它。）
+
+在代�中，�能的情况下，使用 IS_ENABLED ��转化�个 Kconfig 标记为 C 的布尔
+表达�，并在正常的 C �件中使用它：
+
+        if (IS_ENABLED(CONFIG_SOMETHING)) {
+                ...
+        }
+
+编译器会无�件地�常数�并，就�使用 #ifdef 那样，包�或排除代��，所以这�会
+带�任何�行时开销。然而，这�方法�旧�许 C 编译器查看�内的代�，并检查它的正确
+性（语法，类型，符�引用，等等）。因此，如果�件�满足，代��内的引用符�将�存在，
+你必须继续使用 #ifdef。
+
+在任何有�义的 #if 或 #ifdef �的末尾（超过几行），在 #endif �一行的��写下
+注释，指出该�件表达�被使用。例如：
+
+        #ifdef CONFIG_SOMETHING
+        ...
+        #endif /* CONFIG_SOMETHING */
+
 
                 附录 I：�考
 
-The C Programming Language, 第二版, 作者Brian W. Kernighan和Denni
-M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (软皮),
-0-13-110370-9 (硬皮). URL: http://cm.bell-labs.com/cm/cs/cbook/
+The C Programming Language, 第二版
+作者：Brian W. Kernighan 和 Denni M. Ritchie.
+Prentice Hall, Inc., 1988.
+ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮).
 
-The Practice of Programming 作者Brian W. Kernighan和Rob Pike.  Addison-Wesley,
-Inc., 1999.  ISBN 0-201-61586-X.  URL: http://cm.bell-labs.com/cm/cs/tpop/
+The Practice of Programming
+作者：Brian W. Kernighan 和 Rob Pike.
+Addison-Wesley, Inc., 1999.
+ISBN 0-201-61586-X.
 
-cpp，gcc，gcc internals和indent的GNU手册——和K&R�本文相符�的部分，全部�以在
-http://www.gnu.org/manual/找到
+GNU 手册 - �循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent,
+都�以从 http://www.gnu.org/manual/ 找到
 
 WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/
 
-Kernel CodingStyle，作者greg@kroah.com�表于OLS 2002：
+Kernel CodingStyle，作者 greg@kroah.com �表于OLS 2002：
 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
-
---
-最�更新于2007年7月13日。
diff --git a/Makefile b/Makefile
index 8d1301ab59fd..801457b847a4 100644
--- a/Makefile
+++ b/Makefile
@@ -1412,8 +1412,11 @@ $(help-board-dirs): help-%:
 
 # Documentation targets
 # ---------------------------------------------------------------------------
-%docs: scripts_basic FORCE
+DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
+PHONY += $(DOC_TARGETS)
+$(DOC_TARGETS): scripts_basic FORCE
         $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
+        $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
         $(Q)$(MAKE) $(build)=Documentation/DocBook $@
 
 else # KBUILD_EXTMOD
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2fc8fad5195e..27757c21551a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -59,6 +59,12 @@ Output format selection (mutually exclusive):
   -text                 Output plain text format.
 
 Output selection (mutually exclusive):
+  -export               Only output documentation for symbols that have been
+                        exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+                        in the same FILE.
+  -internal             Only output documentation for symbols that have NOT been
+                        exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+                        in the same FILE.
   -function NAME        Only output documentation for the given function(s)
                         or DOC: section title(s). All other functions and DOC:
                         sections are ignored. May be specified multiple times.
@@ -68,6 +74,8 @@ Output selection (mutually exclusive):
 
 Output selection modifiers:
   -no-doc-sections      Do not output DOC: sections.
+  -enable-lineno        Enable output of #define LINENO lines. Only works with
+                        reStructuredText format.
 
 Other parameters:
   -v                    Verbose output, more warnings and other information.
@@ -206,6 +214,10 @@ my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 my $type_enum_full = '\&(enum)\s*([_\w]+)';
 my $type_struct_full = '\&(struct)\s*([_\w]+)';
+my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
+my $type_union_full = '\&(union)\s*([_\w]+)';
+my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
+my $type_member_func = $type_member . '\(\)';
 
 # Output conversion substitutions.
 #  One for each output format
@@ -274,10 +286,16 @@ my $blankline_text = "";
 # rst-mode
 my @highlights_rst = (
                        [$type_constant, "``\$1``"],
-                       [$type_func, "\\:c\\:func\\:`\$1`"],
+                       # Note: need to escape () to avoid func matching later
+                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
+                       [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
+                       [$type_func, "\\:c\\:func\\:`\$1()`"],
                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
-                       [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
+                       [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+                       [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+                       # in rst this can refer to any type
+                       [$type_struct, "\\:c\\:type\\:`\$1`"],
                        [$type_param, "**\$1**"]
                       );
 my $blankline_rst = "\n";
@@ -303,10 +321,19 @@ my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
 my $no_doc_sections = 0;
+my $enable_lineno = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
 my $modulename = "Kernel API";
-my $function_only = 0;
+
+use constant {
+    OUTPUT_ALL          => 0, # output all symbols and doc sections
+    OUTPUT_INCLUDE      => 1, # output only specified symbols
+    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
+    OUTPUT_EXPORTED     => 3, # output exported symbols
+    OUTPUT_INTERNAL     => 4, # output non-exported symbols
+};
+my $output_selection = OUTPUT_ALL;
 my $show_not_found = 0;
 
 my @build_time;
@@ -327,6 +354,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
 # could cause "use of undefined value" or other bugs.
 my ($function, %function_table, %parametertypes, $declaration_purpose);
+my $declaration_start_line;
 my ($type, $declaration_name, $return_type);
 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
 
@@ -344,52 +372,62 @@ my $section_counter = 0;
 
 my $lineprefix="";
 
-# states
-# 0 - normal code
-# 1 - looking for function name
-# 2 - scanning field start.
-# 3 - scanning prototype.
-# 4 - documentation block
-# 5 - gathering documentation outside main block
+# Parser states
+use constant {
+    STATE_NORMAL        => 0, # normal code
+    STATE_NAME          => 1, # looking for function name
+    STATE_FIELD         => 2, # scanning field start
+    STATE_PROTO         => 3, # scanning prototype
+    STATE_DOCBLOCK      => 4, # documentation block
+    STATE_INLINE        => 5, # gathering documentation outside main block
+};
 my $state;
 my $in_doc_sect;
 
-# Split Doc State
-# 0 - Invalid (Before start or after finish)
-# 1 - Is started (the /** was found inside a struct)
-# 2 - The @parameter header was found, start accepting multi paragraph text.
-# 3 - Finished (the */ was found)
-# 4 - Error - Comment without header was found. Spit a warning as it's not
-#     proper kernel-doc and ignore the rest.
-my $split_doc_state;
+# Inline documentation state
+use constant {
+    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
+    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
+    STATE_INLINE_TEXT   => 2, # looking for member documentation
+    STATE_INLINE_END    => 3, # done
+    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
+                              # Spit a warning as it's not
+                              # proper kernel-doc and ignore the rest.
+};
+my $inline_doc_state;
 
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
 
-my $doc_special = "\@\%\$\&";
-
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
-my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+# @params and a strictly limited set of supported section names
+my $doc_sect = $doc_com . 
+    '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
-my $doc_split_start = '^\s*/\*\*\s*$';
-my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
-my $doc_split_end = '^\s*\*/\s*$';
+my $doc_inline_start = '^\s*/\*\*\s*$';
+my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_end = '^\s*\*/\s*$';
+my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
 
-my %constants;
 my %parameterdescs;
+my %parameterdesc_start_lines;
 my @parameterlist;
 my %sections;
 my @sectionlist;
+my %section_start_lines;
 my $sectcheck;
 my $struct_actual;
 
 my $contents = "";
+my $new_start_line = 0;
+
+# the canonical section names. see also $doc_sect above.
 my $section_default = "Description";    # default section
 my $section_intro = "Introduction";
 my $section = $section_default;
@@ -437,19 +475,27 @@ while ($ARGV[0] =~ m/^-(.*)/) {
     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
         $modulename = shift @ARGV;
     } elsif ($cmd eq "-function") { # to only output specific functions
-        $function_only = 1;
+        $output_selection = OUTPUT_INCLUDE;
         $function = shift @ARGV;
         $function_table{$function} = 1;
-    } elsif ($cmd eq "-nofunction") { # to only output specific functions
-        $function_only = 2;
+    } elsif ($cmd eq "-nofunction") { # output all except specific functions
+        $output_selection = OUTPUT_EXCLUDE;
         $function = shift @ARGV;
         $function_table{$function} = 1;
+    } elsif ($cmd eq "-export") { # only exported symbols
+        $output_selection = OUTPUT_EXPORTED;
+        %function_table = ()
+    } elsif ($cmd eq "-internal") { # only non-exported symbols
+        $output_selection = OUTPUT_INTERNAL;
+        %function_table = ()
     } elsif ($cmd eq "-v") {
         $verbose = 1;
     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
         usage();
     } elsif ($cmd eq '-no-doc-sections') {
             $no_doc_sections = 1;
+    } elsif ($cmd eq '-enable-lineno') {
+            $enable_lineno = 1;
     } elsif ($cmd eq '-show-not-found') {
         $show_not_found = 1;
     }
@@ -467,6 +513,13 @@ sub get_kernel_version() {
     return $version;
 }
 
+#
+sub print_lineno {
+    my $lineno = shift;
+    if ($enable_lineno && defined($lineno)) {
+        print "#define LINENO " . $lineno . "\n";
+    }
+}
 ##
 # dumps section contents to arrays/hashes intended for that purpose.
 #
@@ -475,28 +528,32 @@ sub dump_section {
     my $name = shift;
     my $contents = join "\n", @_;
 
-    if ($name =~ m/$type_constant/) {
-        $name = $1;
-#       print STDERR "constant section '$1' = '$contents'\n";
-        $constants{$name} = $contents;
-    } elsif ($name =~ m/$type_param/) {
+    if ($name =~ m/$type_param/) {
 #       print STDERR "parameter def '$1' = '$contents'\n";
         $name = $1;
         $parameterdescs{$name} = $contents;
         $sectcheck = $sectcheck . $name . " ";
+        $parameterdesc_start_lines{$name} = $new_start_line;
+        $new_start_line = 0;
     } elsif ($name eq "@\.\.\.") {
 #       print STDERR "parameter def '...' = '$contents'\n";
         $name = "...";
         $parameterdescs{$name} = $contents;
         $sectcheck = $sectcheck . $name . " ";
+        $parameterdesc_start_lines{$name} = $new_start_line;
+        $new_start_line = 0;
     } else {
 #       print STDERR "other section '$name' = '$contents'\n";
         if (defined($sections{$name}) && ($sections{$name} ne "")) {
-                print STDERR "${file}:$.: error: duplicate section name '$name'\n";
-                ++$errors;
+            print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
+            ++$warnings;
+            $sections{$name} .= $contents;
+        } else {
+            $sections{$name} = $contents;
+            push @sectionlist, $name;
+            $section_start_lines{$name} = $new_start_line;
+            $new_start_line = 0;
         }
-        $sections{$name} = $contents;
-        push @sectionlist, $name;
     }
 }
 
@@ -512,15 +569,17 @@ sub dump_doc_section {
         return;
     }
 
-    if (($function_only == 0) ||
-        ( $function_only == 1 && defined($function_table{$name})) ||
-        ( $function_only == 2 && !defined($function_table{$name})))
+    if (($output_selection == OUTPUT_ALL) ||
+        ($output_selection == OUTPUT_INCLUDE &&
+         defined($function_table{$name})) ||
+        ($output_selection == OUTPUT_EXCLUDE &&
+         !defined($function_table{$name})))
     {
         dump_section($file, $name, $contents);
         output_blockhead({'sectionlist' => \@sectionlist,
                           'sections' => \%sections,
                           'module' => $modulename,
-                          'content-only' => ($function_only != 0), });
+                          'content-only' => ($output_selection != OUTPUT_ALL), });
     }
 }
 
@@ -1736,7 +1795,10 @@ sub output_blockhead_rst(%) {
     my ($parameter, $section);
 
     foreach $section (@{$args{'sectionlist'}}) {
-        print "**$section**\n\n";
+        if ($output_selection != OUTPUT_INCLUDE) {
+            print "**$section**\n\n";
+        }
+        print_lineno($section_start_lines{$section});
         output_highlight_rst($args{'sections'}{$section});
         print "\n";
     }
@@ -1753,19 +1815,14 @@ sub output_highlight_rst {
     die $@ if $@;
 
     foreach $line (split "\n", $contents) {
-        if ($line eq "") {
-            print $lineprefix, $blankline;
-        } else {
-            $line =~ s/\\\\\\/\&/g;
-            print $lineprefix, $line;
-        }
-        print "\n";
+        print $lineprefix . $line . "\n";
     }
 }
 
 sub output_function_rst(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
+    my $oldprefix = $lineprefix;
     my $start;
 
     print ".. c:function:: ";
@@ -1790,29 +1847,37 @@ sub output_function_rst(%) {
             print $type . " " . $parameter;
         }
     }
-    print ")\n\n    " . $args{'purpose'} . "\n\n";
+    print ")\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print ":Parameters:\n\n";
+    print "**Parameters**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
         my $parameter_name = $parameter;
         #$parameter_name =~ s/\[.*//;
         $type = $args{'parametertypes'}{$parameter};
 
         if ($type ne "") {
-            print "      ``$type $parameter``\n";
+            print "``$type $parameter``\n";
         } else {
-            print "      ``$parameter``\n";
+            print "``$parameter``\n";
         }
-        if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
-            my $oldprefix = $lineprefix;
-            $lineprefix = "        ";
+
+        print_lineno($parameterdesc_start_lines{$parameter_name});
+
+        if (defined($args{'parameterdescs'}{$parameter_name}) &&
+            $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
             output_highlight_rst($args{'parameterdescs'}{$parameter_name});
-            $lineprefix = $oldprefix;
         } else {
-            print "\n        _undescribed_\n";
+            print "  *undescribed*\n";
         }
         print "\n";
     }
+
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
@@ -1820,10 +1885,11 @@ sub output_section_rst(%) {
     my %args = %{$_[0]};
     my $section;
     my $oldprefix = $lineprefix;
-    $lineprefix = "        ";
+    $lineprefix = "";
 
     foreach $section (@{$args{'sectionlist'}}) {
-        print ":$section:\n\n";
+        print "**$section**\n\n";
+        print_lineno($section_start_lines{$section});
         output_highlight_rst($args{'sections'}{$section});
         print "\n";
     }
@@ -1834,24 +1900,28 @@ sub output_section_rst(%) {
 sub output_enum_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
+    my $oldprefix = $lineprefix;
     my $count;
     my $name = "enum " . $args{'enum'};
 
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print "..\n\n:Constants:\n\n";
-    my $oldprefix = $lineprefix;
-    $lineprefix = "    ";
+    print "**Constants**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        print "  `$parameter`\n";
+        print "``$parameter``\n";
         if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
             output_highlight_rst($args{'parameterdescs'}{$parameter});
         } else {
-            print "    undescribed\n";
+            print "  *undescribed*\n";
         }
         print "\n";
     }
+
     $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
@@ -1859,30 +1929,37 @@ sub output_enum_rst(%) {
 sub output_typedef_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
-    my $count;
+    my $oldprefix = $lineprefix;
     my $name = "typedef " . $args{'typedef'};
 
-    ### FIXME: should the name below contain "typedef" or not?
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
 sub output_struct_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
+    my $oldprefix = $lineprefix;
     my $name = $args{'type'} . " " . $args{'struct'};
 
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print ":Definition:\n\n";
-    print " ::\n\n";
+    print "**Definition**\n\n";
+    print "::\n\n";
     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
         if ($parameter =~ /^#/) {
-            print "    " . "$parameter\n";
+            print "  " . "$parameter\n";
             next;
         }
 
@@ -1903,7 +1980,8 @@ sub output_struct_rst(%) {
     }
     print "  };\n\n";
 
-    print ":Members:\n\n";
+    print "**Members**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
         ($parameter =~ /^#/) && next;
 
@@ -1912,14 +1990,14 @@ sub output_struct_rst(%) {
 
         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
         $type = $args{'parametertypes'}{$parameter};
-        print "      `$type $parameter`" . "\n";
-        my $oldprefix = $lineprefix;
-        $lineprefix = "        ";
+        print_lineno($parameterdesc_start_lines{$parameter_name});
+        print "``$type $parameter``\n";
         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
-        $lineprefix = $oldprefix;
         print "\n";
     }
     print "\n";
+
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
@@ -1969,9 +2047,13 @@ sub output_declaration {
     my $name = shift;
     my $functype = shift;
     my $func = "output_${functype}_$output_mode";
-    if (($function_only==0) ||
-        ( $function_only == 1 && defined($function_table{$name})) ||
-        ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
+    if (($output_selection == OUTPUT_ALL) ||
+        (($output_selection == OUTPUT_INCLUDE ||
+          $output_selection == OUTPUT_EXPORTED) &&
+         defined($function_table{$name})) ||
+        (($output_selection == OUTPUT_EXCLUDE ||
+          $output_selection == OUTPUT_INTERNAL) &&
+         !($functype eq "function" && defined($function_table{$name}))))
     {
         &$func(@_);
         $section_counter++;
@@ -2471,7 +2553,6 @@ sub dump_function($$) {
 
 sub reset_state {
     $function = "";
-    %constants = ();
     %parameterdescs = ();
     %parametertypes = ();
     @parameterlist = ();
@@ -2481,8 +2562,8 @@ sub reset_state {
     $struct_actual = "";
     $prototype = "";
 
-    $state = 0;
-    $split_doc_state = 0;
+    $state = STATE_NORMAL;
+    $inline_doc_state = STATE_INLINE_NA;
 }
 
 sub tracepoint_munge($) {
@@ -2545,7 +2626,7 @@ sub syscall_munge() {
         }
 }
 
-sub process_state3_function($$) {
+sub process_proto_function($$) {
     my $x = shift;
     my $file = shift;
 
@@ -2575,7 +2656,7 @@ sub process_state3_function($$) {
     }
 }
 
-sub process_state3_type($$) {
+sub process_proto_type($$) {
     my $x = shift;
     my $file = shift;
 
@@ -2657,6 +2738,7 @@ sub process_file($) {
     my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
     my ($orig_file) = @_;
+    my $leading_space;
 
     if (defined($ENV{'SRCTREE'})) {
         $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
@@ -2674,6 +2756,17 @@ sub process_file($) {
         return;
     }
 
+    # two passes for -export and -internal
+    if ($output_selection == OUTPUT_EXPORTED ||
+        $output_selection == OUTPUT_INTERNAL) {
+        while (<IN>) {
+            if (/$export_symbol/o) {
+                $function_table{$2} = 1;
+            }
+        }
+        seek(IN, 0, 0);
+    }
+
     $. = 1;
 
     $section_counter = 0;
@@ -2681,15 +2774,18 @@ sub process_file($) {
         while (s/\\\s*$//) {
             $_ .= <IN>;
         }
-        if ($state == 0) {
+        if ($state == STATE_NORMAL) {
             if (/$doc_start/o) {
-                $state = 1;             # next line is always the function name
+                $state = STATE_NAME;    # next line is always the function name
                 $in_doc_sect = 0;
+                $declaration_start_line = $. + 1;
             }
-        } elsif ($state == 1) { # this line is the function name (always)
+        } elsif ($state == STATE_NAME) {# this line is the function name (always)
             if (/$doc_block/o) {
-                $state = 4;
+                $state = STATE_DOCBLOCK;
                 $contents = "";
+                $new_start_line = $. + 1;
+
                 if ( $1 eq "" ) {
                         $section = $section_intro;
                 } else {
@@ -2702,7 +2798,12 @@ sub process_file($) {
                     $identifier = $1;
                 }
 
-                $state = 2;
+                $state = STATE_FIELD;
+                # if there's no @param blocks need to set up default section
+                # here
+                $contents = "";
+                $section = $section_default;
+                $new_start_line = $. + 1;
                 if (/-(.*)/) {
                     # strip leading/trailing/multiple spaces
                     $descr= $1;
@@ -2740,13 +2841,25 @@ sub process_file($) {
                 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
                 " - I thought it was a doc line\n";
                 ++$warnings;
-                $state = 0;
+                $state = STATE_NORMAL;
             }
-        } elsif ($state == 2) { # look for head: lines, and include content
-            if (/$doc_sect/o) {
+        } elsif ($state == STATE_FIELD) {       # look for head: lines, and include content
+            if (/$doc_sect/i) { # case insensitive for supported section names
                 $newsection = $1;
                 $newcontents = $2;
 
+                # map the supported section names to the canonical names
+                if ($newsection =~ m/^description$/i) {
+                    $newsection = $section_default;
+                } elsif ($newsection =~ m/^context$/i) {
+                    $newsection = $section_context;
+                } elsif ($newsection =~ m/^returns?$/i) {
+                    $newsection = $section_return;
+                } elsif ($newsection =~ m/^\@return$/) {
+                    # special: @return is a section, not a param description
+                    $newsection = $section_return;
+                }
+
                 if (($contents ne "") && ($contents ne "\n")) {
                     if (!$in_doc_sect && $verbose) {
                         print STDERR "${file}:$.: warning: contents before sections\n";
@@ -2759,14 +2872,16 @@ sub process_file($) {
                 $in_doc_sect = 1;
                 $in_purpose = 0;
                 $contents = $newcontents;
+                $new_start_line = $.;
+                while ((substr($contents, 0, 1) eq " ") ||
+                       substr($contents, 0, 1) eq "\t") {
+                    $contents = substr($contents, 1);
+                }
                 if ($contents ne "") {
-                    while ((substr($contents, 0, 1) eq " ") ||
-                        substr($contents, 0, 1) eq "\t") {
-                            $contents = substr($contents, 1);
-                    }
                     $contents .= "\n";
                 }
                 $section = $newsection;
+                $leading_space = undef;
             } elsif (/$doc_end/) {
                 if (($contents ne "") && ($contents ne "\n")) {
                     dump_section($file, $section, xml_escape($contents));
@@ -2780,7 +2895,7 @@ sub process_file($) {
                 }
 
                 $prototype = "";
-                $state = 3;
+                $state = STATE_PROTO;
                 $brcount = 0;
 #               print STDERR "end of doc comment, looking for prototype\n";
             } elsif (/$doc_content/) {
@@ -2791,6 +2906,7 @@ sub process_file($) {
                         dump_section($file, $section, xml_escape($contents));
                         $section = $section_default;
                         $contents = "";
+                        $new_start_line = $.;
                     } else {
                         $contents .= "\n";
                     }
@@ -2801,87 +2917,86 @@ sub process_file($) {
                     $declaration_purpose .= " " . xml_escape($1);
                     $declaration_purpose =~ s/\s+/ /g;
                 } else {
-                    $contents .= $1 . "\n";
+                    my $cont = $1;
+                    if ($section =~ m/^@/ || $section eq $section_context) {
+                        if (!defined $leading_space) {
+                            if ($cont =~ m/^(\s+)/) {
+                                $leading_space = $1;
+                            } else {
+                                $leading_space = "";
+                            }
+                        }
+
+                        $cont =~ s/^$leading_space//;
+                    }
+                    $contents .= $cont . "\n";
                 }
             } else {
                 # i dont know - bad line?  ignore.
                 print STDERR "${file}:$.: warning: bad line: $_";
                 ++$warnings;
             }
-        } elsif ($state == 5) { # scanning for split parameters
+        } elsif ($state == STATE_INLINE) { # scanning for inline parameters
             # First line (state 1) needs to be a @parameter
-            if ($split_doc_state == 1 && /$doc_split_sect/o) {
+            if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
                 $section = $1;
                 $contents = $2;
+                $new_start_line = $.;
                 if ($contents ne "") {
                     while ((substr($contents, 0, 1) eq " ") ||
                            substr($contents, 0, 1) eq "\t") {
                         $contents = substr($contents, 1);
                     }
-                $contents .= "\n";
+                    $contents .= "\n";
                 }
-                $split_doc_state = 2;
+                $inline_doc_state = STATE_INLINE_TEXT;
             # Documentation block end */
-            } elsif (/$doc_split_end/) {
+            } elsif (/$doc_inline_end/) {
                 if (($contents ne "") && ($contents ne "\n")) {
                     dump_section($file, $section, xml_escape($contents));
                     $section = $section_default;
                     $contents = "";
                 }
-                $state = 3;
-                $split_doc_state = 0;
+                $state = STATE_PROTO;
+                $inline_doc_state = STATE_INLINE_NA;
             # Regular text
             } elsif (/$doc_content/) {
-                if ($split_doc_state == 2) {
+                if ($inline_doc_state == STATE_INLINE_TEXT) {
                     $contents .= $1 . "\n";
-                } elsif ($split_doc_state == 1) {
-                    $split_doc_state = 4;
+                    # nuke leading blank lines
+                    if ($contents =~ /^\s*$/) {
+                        $contents = "";
+                    }
+                } elsif ($inline_doc_state == STATE_INLINE_NAME) {
+                    $inline_doc_state = STATE_INLINE_ERROR;
                     print STDERR "Warning(${file}:$.): ";
                     print STDERR "Incorrect use of kernel-doc format: $_";
                     ++$warnings;
                 }
             }
-        } elsif ($state == 3) { # scanning for function '{' (end of prototype)
-            if (/$doc_split_start/) {
-                $state = 5;
-                $split_doc_state = 1;
+        } elsif ($state == STATE_PROTO) {       # scanning for function '{' (end of prototype)
+            if (/$doc_inline_start/) {
+                $state = STATE_INLINE;
+                $inline_doc_state = STATE_INLINE_NAME;
             } elsif ($decl_type eq 'function') {
-                process_state3_function($_, $file);
+                process_proto_function($_, $file);
             } else {
-                process_state3_type($_, $file);
+                process_proto_type($_, $file);
             }
-        } elsif ($state == 4) {
-                # Documentation block
-                if (/$doc_block/) {
-                        dump_doc_section($file, $section, xml_escape($contents));
-                        $contents = "";
-                        $function = "";
-                        %constants = ();
-                        %parameterdescs = ();
-                        %parametertypes = ();
-                        @parameterlist = ();
-                        %sections = ();
-                        @sectionlist = ();
-                        $prototype = "";
-                        if ( $1 eq "" ) {
-                                $section = $section_intro;
-                        } else {
-                                $section = $1;
-                        }
-                }
-                elsif (/$doc_end/)
+        } elsif ($state == STATE_DOCBLOCK) {
+                if (/$doc_end/)
                 {
                         dump_doc_section($file, $section, xml_escape($contents));
+                        $section = $section_default;
                         $contents = "";
                         $function = "";
-                        %constants = ();
                         %parameterdescs = ();
                         %parametertypes = ();
                         @parameterlist = ();
                         %sections = ();
                         @sectionlist = ();
                         $prototype = "";
-                        $state = 0;
+                        $state = STATE_NORMAL;
                 }
                 elsif (/$doc_content/)
                 {
@@ -2898,7 +3013,7 @@ sub process_file($) {
     }
     if ($initial_section_counter == $section_counter) {
         print STDERR "${file}:1: warning: no structured comments found\n";
-        if (($function_only == 1) && ($show_not_found == 1)) {
+        if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
             print STDERR "    Was looking for '$_'.\n" for keys %function_table;
         }
         if ($output_mode eq "xml") {