samsung_sm8750/android_kernel_samsung_sm8750
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge tag 'docs-for-linus' of git://git.lwn.net/linux

Browse Source 
Pull documentation updates from Jonathan Corbet:
 "Some big changes this month, headlined by the addition of a new
  formatted documentation mechanism based on the Sphinx system.

  The objectives here are to make it easier to create better-integrated
  (and more attractive) documents while (eventually) dumping our
  one-of-a-kind, cobbled-together system for something that is widely
  used and maintained by others.  There's a fair amount of information
  what's being done, why, and how to use it in:

    https://lwn.net/Articles/692704/
    https://lwn.net/Articles/692705/

  Closer to home, Documentation/kernel-documentation.rst describes how
  it works.

  For now, the new system exists alongside the old one; you should soon
  see the GPU documentation converted over in the DRM pull and some
  significant media conversion work as well.  Once all the docs have
  been moved over and we're convinced that the rough edges (of which are
  are a few) have been smoothed over, the DocBook-based stuff should go
  away.

  Primary credit is to Jani Nikula for doing the heavy lifting to make
  this stuff actually work; there has also been notable effort from
  Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab.

  Expect a couple of conflicts on the new index.rst file over the course
  of the merge window; they are trivially resolvable.  That file may be
  a bit of a conflict magnet in the short term, but I don't expect that
  situation to last for any real length of time.

  Beyond that, of course, we have the usual collection of tweaks,
  updates, and typo fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits)
  doc-rst: kernel-doc: fix handling of address_space tags
  Revert "doc/sphinx: Enable keep_warnings"
  doc-rst: kernel-doc directive, fix state machine reporter
  docs: deprecate kernel-doc-nano-HOWTO.txt
  doc/sphinx: Enable keep_warnings
  Documentation: add watermark_scale_factor to the list of vm systcl file
  kernel-doc: Fix up warning output
  docs: Get rid of some kernel-documentation warnings
  doc-rst: add an option to ignore DocBooks when generating docs
  workqueue: Fix a typo in workqueue.txt
  Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
  Documentation/sphinx: skip build if user requested specific DOCBOOKS
  Documentation: add cleanmediadocs to the documentation targets
  Add .pyc files to .gitignore
  Doc: PM: Fix a typo in intel_powerclamp.txt
  doc-rst: flat-table directive - initial implementation
  Documentation: add meta-documentation for Sphinx and kernel-doc
  Documentation: tiny typo fix in usb/gadget_multi.txt
  Documentation: fix wrong value in md.txt
  bcache: documentation formatting, edited for clarity, stripe alignment notes
  ...
This commit is contained in:
Linus Torvalds
2016-07-26 13:05:11 -07:00
parent 015cd867e5 a88b1672d4
commit 0f776dc377
30 changed files with 2645 additions and 422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
output
*.pyc

4
Documentation/00-INDEX
View File

@@ -255,10 +255,10 @@ kbuild/
- directory with info about the kernel build process.
kdump/
- directory with mini HowTo on getting the crash dump code to work.
kernel-doc-nano-HOWTO.txt
- mini HowTo on generation and location of kernel documentation files.
kernel-docs.txt
- listing of various WWW + books that document kernel internals.
kernel-documentation.rst
- how to write and format reStructuredText kernel documentation
kernel-parameters.txt
- summary listing of command line / boot prompt args for the kernel.
kernel-per-CPU-kthreads.txt

2
Documentation/CodingStyle
View File

@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does
it.
When commenting the kernel API functions, please use the kernel-doc format.
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
for details.
Linux style for comments is the C89 "/* ... */" style.

28
Documentation/DocBook/Makefile
View File

@@ -6,6 +6,8 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
ifeq ($(IGNORE_DOCBOOKS),)
DOCBOOKS := z8530book.xml device-drivers.xml \
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
writing_usb_driver.xml networking.xml \
@@ -33,10 +35,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 +61,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
@@ -216,10 +217,24 @@ silent_gen_xml = :
-e "s/>/\\>/g"; \
echo "</programlisting>") > $@
else
# Needed, due to cleanmediadocs
include Documentation/DocBook/media/Makefile
htmldocs:
pdfdocs:
psdocs:
xmldocs:
installmandocs:
endif # IGNORE_DOCBOOKS
###
# Help targets as used by the top-level makefile
dochelp:
@echo ' Linux kernel internal documentation in different formats:'
@echo ' Linux kernel internal documentation in different formats (DocBook):'
@echo ' htmldocs - HTML'
@echo ' pdfdocs - PDF'
@echo ' psdocs - Postscript'
@@ -230,6 +245,9 @@ dochelp:
@echo
@echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
@echo ' valid values for DOCBOOKS are: $(DOCBOOKS)'
@echo
@echo " make IGNORE_DOCBOOKS=1 [target] Don't generate docs from Docbook"
@echo ' This is useful to generate only the ReST docs (Sphinx)'
###

78
Documentation/Makefile.sphinx Normal file
View File

@@ -0,0 +1,78 @@
# -*- 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 ifneq ($(DOCBOOKS),)
# Skip Sphinx build if the user explicitly requested DOCBOOKS.
.DEFAULT:
@echo " SKIP Sphinx $@ target (DOCBOOKS specified)."
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:
cleanmediadocs:
cleandocs:
$(Q)rm -rf $(BUILDDIR)
dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
@echo ' htmldocs - HTML'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' cleandocs - clean all generated files'
endif # HAVE_SPHINX

193
Documentation/bcache.txt
View File

@@ -1,4 +1,4 @@
Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be
Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
nice if you could use them as cache... Hence bcache.
Wiki and git repositories are at:
@@ -8,7 +8,7 @@ Wiki and git repositories are at:
It's designed around the performance characteristics of SSDs - it only allocates
in erase block sized buckets, and it uses a hybrid btree/log to track cached
extants (which can be anywhere from a single sector to the bucket size). It's
extents (which can be anywhere from a single sector to the bucket size). It's
designed to avoid random writes at all costs; it fills up an erase block
sequentially, then issues a discard before reusing it.
@@ -55,7 +55,10 @@ immediately. Without udev, you can manually register devices like this:
Registering the backing device makes the bcache device show up in /dev; you can
now format it and use it as normal. But the first time using a new bcache
device, it'll be running in passthrough mode until you attach it to a cache.
See the section on attaching.
If you are thinking about using bcache later, it is recommended to setup all your
slow devices as bcache backing devices without a cache, and you can choose to add
a caching device later.
See 'ATTACHING' section below.
The devices show up as:
@@ -72,12 +75,14 @@ To get started:
mount /dev/bcache0 /mnt
You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
You can also control them through /sys/fs//bcache/<cset-uuid>/ .
Cache devices are managed as sets; multiple caches per set isn't supported yet
but will allow for mirroring of metadata and dirty data in the future. Your new
cache set shows up as /sys/fs/bcache/<UUID>
ATTACHING:
ATTACHING
---------
After your cache device and backing device are registered, the backing device
must be attached to your cache set to enable caching. Attaching a backing
@@ -105,7 +110,8 @@ but all the cached data will be invalidated. If there was dirty data in the
cache, don't expect the filesystem to be recoverable - you will have massive
filesystem corruption, though ext4's fsck does work miracles.
ERROR HANDLING:
ERROR HANDLING
--------------
Bcache tries to transparently handle IO errors to/from the cache device without
affecting normal operation; if it sees too many errors (the threshold is
@@ -127,12 +133,181 @@ the backing devices to passthrough mode.
writeback mode). It currently doesn't do anything intelligent if it fails to
read some of the dirty data, though.
TROUBLESHOOTING PERFORMANCE:
HOWTO/COOKBOOK
--------------
A) Starting a bcache with a missing caching device
If registering the backing device doesn't help, it's already there, you just need
to force it to run without the cache:
host:~# echo /dev/sdb1 > /sys/fs/bcache/register
[ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
Next, you try to register your caching device if it's present. However
if it's absent, or registration fails for some reason, you can still
start your bcache without its cache, like so:
host:/sys/block/sdb/sdb1/bcache# echo 1 > running
Note that this may cause data loss if you were running in writeback mode.
B) Bcache does not find its cache
host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
[ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
[ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8
[ 1933.478179] : cache set not found
In this case, the caching device was simply not registered at boot
or disappeared and came back, and needs to be (re-)registered:
host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
C) Corrupt bcache crashes the kernel at device registration time:
This should never happen. If it does happen, then you have found a bug!
Please report it to the bcache development list: linux-bcache@vger.kernel.org
Be sure to provide as much information that you can including kernel dmesg
output if available so that we may assist.
D) Recovering data without bcache:
If bcache is not available in the kernel, a filesystem on the backing
device is still available at an 8KiB offset. So either via a loopdev
of the backing device created with --offset 8K, or any value defined by
--data-offset when you originally formatted bcache with `make-bcache`.
For example:
losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
This should present your unmodified backing device data in /dev/loop0
If your cache is in writethrough mode, then you can safely discard the
cache device without loosing data.
E) Wiping a cache device
host:~# wipefs -a /dev/sdh2
16 bytes were erased at offset 0x1018 (bcache)
they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
After you boot back with bcache enabled, you recreate the cache and attach it:
host:~# make-bcache -C /dev/sdh2
UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
version: 0
nbuckets: 106874
block_size: 1
bucket_size: 1024
nr_in_set: 1
nr_this_dev: 0
first_bucket: 1
[ 650.511912] bcache: run_cache_set() invalidating existing data
[ 650.549228] bcache: register_cache() registered cache device sdh2
start backing device with missing cache:
host:/sys/block/md5/bcache# echo 1 > running
attach new cache:
host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
F) Remove or replace a caching device
host:/sys/block/sda/sda7/bcache# echo 1 > detach
[ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
host:~# wipefs -a /dev/nvme0n1p4
wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
Ooops, it's disabled, but not unregistered, so it's still protected
We need to go and unregister it:
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
Now we can wipe it:
host:~# wipefs -a /dev/nvme0n1p4
/dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
G) dm-crypt and bcache
First setup bcache unencrypted and then install dmcrypt on top of
/dev/bcache<N> This will work faster than if you dmcrypt both the backing
and caching devices and then install bcache on top. [benchmarks?]
H) Stop/free a registered bcache to wipe and/or recreate it
Suppose that you need to free up all bcache references so that you can
fdisk run and re-register a changed partition table, which won't work
if there are any active backing or caching devices left on it:
1) Is it present in /dev/bcache* ? (there are times where it won't be)
If so, it's easy:
host:/sys/block/bcache0/bcache# echo 1 > stop
2) But if your backing device is gone, this won't work:
host:/sys/block/bcache0# cd bcache
bash: cd: bcache: No such file or directory
In this case, you may have to unregister the dmcrypt block device that
references this bcache to free it up:
host:~# dmsetup remove oldds1
bcache: bcache_device_free() bcache0 stopped
bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
This causes the backing bcache to be removed from /sys/fs/bcache and
then it can be reused. This would be true of any block device stacking
where bcache is a lower device.
3) In other cases, you can also look in /sys/fs/bcache/:
host:/sys/fs/bcache# ls -l */{cache?,bdev?}
lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
The device names will show which UUID is relevant, cd in that directory
and stop the cache:
host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
This will free up bcache references and let you reuse the partition for
other purposes.
TROUBLESHOOTING PERFORMANCE
---------------------------
Bcache has a bunch of config options and tunables. The defaults are intended to
be reasonable for typical desktop and server workloads, but they're not what you
want for getting the best possible numbers when benchmarking.
- Backing device alignment
The default metadata size in bcache is 8k. If your backing device is
RAID based, then be sure to align this by a multiple of your stride
width using `make-bcache --data-offset`. If you intend to expand your
disk array in the future, then multiply a series of primes by your
raid stripe size to get the disk multiples that you would like.
For example: If you have a 64k stripe size, then the following offset
would provide alignment for many common RAID5 data spindle counts:
64k * 2*2*2*3*3*5*7 bytes = 161280k
That space is wasted, but for only 157.5MB you can grow your RAID 5
volume to the following data-spindle counts without re-aligning:
3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
- Bad write performance
If write performance is not what you expected, you probably wanted to be
@@ -140,7 +315,7 @@ want for getting the best possible numbers when benchmarking.
maturity, but simply because in writeback mode you'll lose data if something
happens to your SSD)
# echo writeback > /sys/block/bcache0/cache_mode
# echo writeback > /sys/block/bcache0/bcache/cache_mode
- Bad performance, or traffic not going to the SSD that you'd expect
@@ -193,7 +368,9 @@ want for getting the best possible numbers when benchmarking.
Solution: warm the cache by doing writes, or use the testing branch (there's
a fix for the issue there).
SYSFS - BACKING DEVICE:
SYSFS - BACKING DEVICE
----------------------
Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
(if attached) /sys/fs/bcache/<cset-uuid>/bdev*

414
Documentation/conf.py Normal file
View File

@@ -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', 'rstFlatTable']
# 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 = '..'

2
Documentation/development-process/4.Coding
View File

@@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc
comments for the future; indeed, this can be a useful activity for
beginning kernel developers. The format of these comments, along with some
information on how to create kerneldoc templates can be found in the file
Documentation/kernel-doc-nano-HOWTO.txt.
Documentation/kernel-documentation.rst.
Anybody who reads through a significant amount of existing kernel code will
note that, often, comments are most notable by their absence. Once again,

2
Documentation/dmaengine/provider.txt
View File

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

10
Documentation/filesystems/ocfs2-online-filecheck.txt
View File

@@ -5,12 +5,12 @@ This document will describe OCFS2 online file check feature.
Introduction
============
OCFS2 is often used in high-availaibility systems. However, OCFS2 usually
OCFS2 is often used in high-availability systems. However, OCFS2 usually
converts the filesystem to read-only when encounters an error. This may not be
necessary, since turning the filesystem read-only would affect other running
processes as well, decreasing availability.
Then, a mount option (errors=continue) is introduced, which would return the
-EIO errno to the calling process and terminate furhter processing so that the
-EIO errno to the calling process and terminate further processing so that the
filesystem is not corrupted further. The filesystem is not converted to
read-only, and the problematic file's inode number is reported in the kernel
log. The user can try to check/fix this file via online filecheck feature.
@@ -44,7 +44,7 @@ There is a sysfs directory for each OCFS2 file system mounting:
/sys/fs/ocfs2/<devname>/filecheck
Here, <devname> indicates the name of OCFS2 volumn device which has been already
Here, <devname> indicates the name of OCFS2 volume device which has been already
mounted. The file above would accept inode numbers. This could be used to
communicate with kernel space, tell which file(inode number) will be checked or
fixed. Currently, three operations are supported, which includes checking
@@ -76,14 +76,14 @@ The output is like this:
This time, the <ERROR> column indicates whether this fix is successful or not.
3. The record cache is used to store the history of check/fix results. It's
defalut size is 10, and can be adjust between the range of 10 ~ 100. You can
default size is 10, and can be adjust between the range of 10 ~ 100. You can
adjust the size like this:
# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
Fixing stuff
============
On receivng the inode, the filesystem would read the inode and the
On receiving the inode, the filesystem would read the inode and the
file metadata. In case of errors, the filesystem would fix the errors
and report the problems it fixed in the kernel log. As a precautionary measure,
the inode must first be checked for errors before performing a final fix.

22
Documentation/index.rst Normal file
View File

@@ -0,0 +1,22 @@
.. 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
kernel-documentation
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

3
Documentation/kernel-doc-nano-HOWTO.txt
View File

@@ -1,3 +1,6 @@
NOTE: this document is outdated and will eventually be removed. See
Documentation/kernel-documentation.rst for current information.
kernel-doc nano-HOWTO
=====================

654
Documentation/kernel-documentation.rst Normal file
View File

@@ -0,0 +1,654 @@
==========================
Linux Kernel Documentation
==========================
Introduction
============
The Linux kernel uses `Sphinx`_ to generate pretty documentation from
`reStructuredText`_ files under ``Documentation``. To build the documentation in
HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
documentation is placed in ``Documentation/output``.
.. _Sphinx: http://www.sphinx-doc.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
The reStructuredText files may contain directives to include structured
documentation comments, or kernel-doc comments, from source files. Usually these
are used to describe the functions and types and design of the code. The
kernel-doc comments have some special structure and formatting, but beyond that
they are also treated as reStructuredText.
There is also the deprecated DocBook toolchain to generate documentation from
DocBook XML template files under ``Documentation/DocBook``. The DocBook files
are to be converted to reStructuredText, and the toolchain is slated to be
removed.
Finally, there are thousands of plain text documentation files scattered around
``Documentation``. Some of these will likely be converted to reStructuredText
over time, but the bulk of them will remain in plain text.
Sphinx Build
============
The usual way to generate the documentation is to run ``make htmldocs`` or
``make pdfdocs``. There are also other formats available, see the documentation
section of ``make help``. The generated documentation is placed in
format-specific subdirectories under ``Documentation/output``.
To generate documentation, Sphinx (``sphinx-build``) must obviously be
installed. For prettier HTML output, the Read the Docs Sphinx theme
(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
needed. All of these are widely available and packaged in distributions.
To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
output.
To remove the generated documentation, run ``make cleandocs``.
Writing Documentation
=====================
Adding new documentation can be as simple as:
1. Add a new ``.rst`` file somewhere under ``Documentation``.
2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
This is usually good enough for simple documentation (like the one you're
reading right now), but for larger documents it may be advisable to create a
subdirectory (or use an existing one). For example, the graphics subsystem
documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
the main index.
See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
to get started with reStructuredText. There are also some `Sphinx specific
markup constructs`_.
.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
Specific guidelines for the kernel documentation
------------------------------------------------
Here are some specific guidelines for the kernel documentation:
* Please don't go overboard with reStructuredText markup. Keep it simple.
* Please stick to this order of heading adornments:
1. ``=`` with overline for document title::
==============
Document title
==============
2. ``=`` for chapters::
Chapters
========
3. ``-`` for sections::
Section
-------
4. ``~`` for subsections::
Subsection
~~~~~~~~~~
Although RST doesn't mandate a specific order ("Rather than imposing a fixed
number and order of section title adornment styles, the order enforced will be
the order as encountered."), having the higher levels the same overall makes
it easier to follow the documents.
list tables
-----------
We recommend the use of *list table* formats. The *list table* formats are
double-stage lists. Compared to the ASCII-art they might not be as
comfortable for
readers of the text files. Their advantage is that they are easy to
create or modify and that the diff of a modification is much more meaningful,
because it is limited to the modified content.
The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:
* column-span: with the role ``cspan`` a cell can be extended through
additional columns
* row-span: with the role ``rspan`` a cell can be extended through
additional rows
* auto span rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automatically inserts (empty)
cells instead of spanning the last cell.
options:
* ``:header-rows:`` [int] count of header rows
* ``:stub-columns:`` [int] count of stub columns
* ``:widths:`` [[int] [int] ... ] widths of columns
* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
roles:
* ``:cspan:`` [int] additional columns (*morecols*)
* ``:rspan:`` [int] additional rows (*morerows*)
The example below shows how to use this markup. The first level of the staged
list is the *table-row*. In the *table-row* there is only one markup allowed,
the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
<last row>`).
.. code-block:: rst
.. flat-table:: table title
:widths: 2 1 1 3
* - head col 1
- head col 2
- head col 3
- head col 4
* - column 1
- field 1.1
- field 1.2 with autospan
* - column 2
- field 2.1
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
* .. _`last row`:
- column 3
Rendered as:
.. flat-table:: table title
:widths: 2 1 1 3
* - head col 1
- head col 2
- head col 3
- head col 4
* - column 1
- field 1.1
- field 1.2 with autospan
* - column 2
- field 2.1
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
* .. _`last row`:
- column 3
Including kernel-doc comments
=============================
The Linux kernel source files may contain structured documentation comments, or
kernel-doc comments to describe the functions and types and design of the
code. The documentation comments may be included to any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.
The kernel-doc directive is of the format::
.. kernel-doc:: source
:option:
The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:
export: *[source-pattern ...]*
Include documentation for all functions in *source* that have been exported
using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
of the files specified by *source-pattern*.
The *source-pattern* is useful when the kernel-doc comments have been placed
in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
Examples::
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: *[source-pattern ...]*
Include documentation for all functions and types in *source* that have
**not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
in *source* or in any of the files specified by *source-pattern*.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
doc: *title*
Include documentation for the ``DOC:`` paragraph identified by *title* in
*source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
is only used as an identifier for the paragraph, and is not included in the
output. Please make sure to have an appropriate heading in the enclosing
reStructuredText document.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
functions: *function* *[...]*
Include documentation for each *function* in *source*.
Example::
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
Without options, the kernel-doc directive includes all documentation comments
from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
Writing kernel-doc comments
===========================
In order to provide embedded, "C" friendly, easy to maintain, but consistent and
extractable overview, function and type documentation, the Linux kernel has
adopted a consistent style for documentation comments. The format for this
documentation is called the kernel-doc format, described below. This style
embeds the documentation within the source files, using a few simple conventions
for adding documentation paragraphs and documenting functions and their
parameters, structures and unions and their members, enumerations, and typedefs.
.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
yet distinctively different, for historical reasons. The kernel source
contains tens of thousands of kernel-doc comments. Please stick to the style
described here.
The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
the documentation build to extract this embedded documentation into the various
HTML, PDF, and other format documents.
In order to provide good documentation of kernel functions and data structures,
please use the following conventions to format your kernel-doc comments in the
Linux kernel source.
How to format kernel-doc comments
---------------------------------
The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
comments so marked will be considered by the ``kernel-doc`` tool. Use it only
for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
should be used as the closing comment marker. The lines in between should be
prefixed by `` * `` (space star space).
The function and type kernel-doc comments should be placed just before the
function or type being described. The overview kernel-doc comments may be freely
placed at the top indentation level.
Example kernel-doc function comment::
/**
* foobar() - Brief description of foobar.
* @arg: Description of argument of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
int foobar(int arg)
The format is similar for documentation for structures, enums, paragraphs,
etc. See the sections below for details.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
descriptions are filtered for special kernel-doc highlights and
cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
Highlights and cross-references
-------------------------------
The following special patterns are recognized in the kernel-doc comment
descriptive text and converted to proper reStructuredText markup and `Sphinx C
Domain`_ references.
.. attention:: The below are **only** recognized within kernel-doc comments,
**not** within normal reStructuredText documents.
``funcname()``
Function reference.
``@parameter``
Name of a function parameter. (No cross-referencing, just formatting.)
``%CONST``
Name of a constant. (No cross-referencing, just formatting.)
``$ENVVAR``
Name of an environment variable. (No cross-referencing, just formatting.)
``&struct name``
Structure reference.
``&enum name``
Enum reference.
``&typedef name``
Typedef reference.
``&struct_name->member`` or ``&struct_name.member``
Structure or union member reference. The cross-reference will be to the struct
or union definition, not the member directly.
``&name``
A generic type reference. Prefer using the full reference described above
instead. This is mostly for legacy comments.
Cross-referencing from reStructuredText
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. highlight:: none
To cross-reference the functions and types defined in the kernel-doc comments
from reStructuredText documents, please use the `Sphinx C Domain`_
references. For example::
See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
While the type reference works with just the type name, without the
struct/union/enum/typedef part in front, you may want to use::
See :c:type:`struct foo <foo>`.
See :c:type:`union bar <bar>`.
See :c:type:`enum baz <baz>`.
See :c:type:`typedef meh <meh>`.
This will produce prettier links, and is in line with how kernel-doc does the
cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation.
Function documentation
----------------------
.. highlight:: c
The general format of a function and function-like macro kernel-doc comment is::
/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.
* @arg2: Describe the second argument.
* One can provide multiple line descriptions
* for arguments.
*
* A longer description, with more discussion of the function function_name()
* that might be useful to those using or modifying it. Begins with an
* empty comment line, and may include additional embedded empty
* comment lines.
*
* The longer description may have multiple paragraphs.
*
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and should
* be placed at the end of the comment block.
*/
The brief description following the function name may span multiple lines, and
ends with an ``@argument:`` description, a blank comment line, or the end of the
comment block.
The kernel-doc function comments describe each parameter to the function, in
order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
must begin on the very next line following the opening brief function
description line, with no intervening blank comment lines. The ``@argument:``
descriptions may span multiple lines. The continuation lines may contain
indentation. If a function parameter is ``...`` (varargs), it should be listed
in kernel-doc notation as: ``@...:``.
The return value, if any, should be described in a dedicated section at the end
of the comment starting with "Return:".
Structure, union, and enumeration documentation
-----------------------------------------------
The general format of a struct, union, and enum kernel-doc comment is::
/**
* struct struct_name - Brief description.
* @member_name: Description of member member_name.
*
* Description of the structure.
*/
Below, "struct" is used to mean structs, unions and enums, and "member" is used
to mean struct and union members as well as enumerations in an enum.
The brief description following the structure name may span multiple lines, and
ends with a ``@member:`` description, a blank comment line, or the end of the
comment block.
The kernel-doc data structure comments describe each member of the structure, in
order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
begin on the very next line following the opening brief function description
line, with no intervening blank comment lines. The ``@member:`` descriptions may
span multiple lines. The continuation lines may contain indentation.
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The structure members may also be documented in-line within the definition::
/**
* struct foo - Brief description.
* @foo: The Foo member.
*/
struct foo {
int foo;
/**
* @bar: The Bar member.
*/
int bar;
/**
* @baz: The Baz member.
*
* Here, the member description may contain several paragraphs.
*/
int baz;
}
Private members
~~~~~~~~~~~~~~~
Inside a struct description, you can use the "private:" and "public:" comment
tags. Structure fields that are inside a "private:" area are not listed in the
generated output documentation. The "private:" and "public:" tags must begin
immediately following a ``/*`` comment marker. They may optionally include
comments between the ``:`` and the ending ``*/`` marker.
Example::
/**
* struct my_struct - short description
* @a: first member
* @b: second member
*
* Longer description
*/
struct my_struct {
int a;
int b;
/* private: internal use only */
int c;
};
Typedef documentation
---------------------
The general format of a typedef kernel-doc comment is::
/**
* typedef type_name - Brief description.
*
* Description of the type.
*/
Overview documentation comments
-------------------------------
To facilitate having source code and comments close together, you can include
kernel-doc documentation blocks that are free-form comments instead of being
kernel-doc for functions, structures, unions, enums, or typedefs. This could be
used for something like a theory of operation for a driver or library code, for
example.
This is done by using a ``DOC:`` section keyword with a section title.
The general format of an overview or high-level documentation comment is::
/**
* DOC: Theory of Operation
*
* The whizbang foobar is a dilly of a gizmo. It can do whatever you
* want it to do, at any time. It reads your mind. Here's how it works.
*
* foo bar splat
*
* The only drawback to this gizmo is that is can sometimes damage
* hardware, software, or its subject(s).
*/
The title following ``DOC:`` acts as a heading within the source file, but also
as an identifier for extracting the documentation comment. Thus, the title must
be unique within the file.
Recommendations
---------------
We definitely need kernel-doc formatted documentation for functions that are
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
We also look to provide kernel-doc formatted documentation for functions
externally visible to other kernel files (not marked "static").
We also recommend providing kernel-doc formatted documentation for private (file
"static") routines, for consistency of kernel source code layout. But this is
lower priority and at the discretion of the MAINTAINER of that kernel source
file.
Data structures visible in kernel include files should also be documented using
kernel-doc formatted comments.
DocBook XML [DEPRECATED]
========================
.. attention::
This section describes the deprecated DocBook XML toolchain. Please do not
create new DocBook XML template files. Please consider converting existing
DocBook XML templates files to Sphinx/reStructuredText.
Converting DocBook to Sphinx
----------------------------
.. highlight:: none
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
which uses ``pandoc`` under the hood. For example::
$ cd Documentation/sphinx
$ ./tmplcvt ../DocBook/in.tmpl ../out.rst
Then edit the resulting rst files to fix any remaining issues, and add the
document in the ``toctree`` in ``Documentation/index.rst``.
Components of the kernel-doc system
-----------------------------------
Many places in the source tree have extractable documentation in the form of
block comments above functions. The components of this system are:
- ``scripts/kernel-doc``
This is a perl script that hunts for the block comments and can mark them up
directly into reStructuredText, DocBook, man, text, and HTML. (No, not
texinfo.)
- ``Documentation/DocBook/*.tmpl``
These are XML template files, which are normal XML files with special
place-holders for where the extracted documentation should go.
- ``scripts/docproc.c``
This is a program for converting XML template files into XML files. When a
file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
able to distinguish between internal and external functions.
It invokes kernel-doc, giving it the list of functions that are to be
documented.
Additionally it is used to scan the XML template files to locate all the files
referenced herein. This is used to generate dependency information as used by
make.
- ``Makefile``
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
DocBook XML files, PostScript files, PDF files, and html files in
Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
- ``Documentation/DocBook/Makefile``
This is where C files are associated with SGML templates.
How to use kernel-doc comments in DocBook XML template files
------------------------------------------------------------
DocBook XML template files (\*.tmpl) are like normal XML files, except that they
can contain escape sequences where extracted documentation should be inserted.
``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
functions that are exported using ``EXPORT_SYMBOL``: the function list is
collected from files listed in ``Documentation/DocBook/Makefile``.
``!I<filename>`` is replaced by the documentation for functions that are **not**
exported using ``EXPORT_SYMBOL``.
``!D<filename>`` is used to name additional files to search for functions
exported using ``EXPORT_SYMBOL``.
``!F<filename> <function [functions...]>`` is replaced by the documentation, in
``<filename>``, for the functions listed.
``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
``<section title>``; do not quote the ``<section title>``.
``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
sections and documented functions, symbols, etc. are used. This makes sense to
use when you use ``!F`` or ``!P`` only and want to verify that all documentation
is included.

5
Documentation/kernel-parameters.txt
View File

@@ -3996,8 +3996,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.

2
Documentation/md.txt
View File

@@ -602,7 +602,7 @@ These currently include
stripe_cache_size (currently raid5 only)
number of entries in the stripe cache. This is writable, but
there are upper and lower limits (32768, 16). Default is 128.
there are upper and lower limits (32768, 17). Default is 256.
strip_cache_active (currently raid5 only)
number of active entries in the stripe cache
preread_bypass_threshold (currently raid5 only)

4
Documentation/mic/mpssd/mpssd.c
View File

@@ -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);

28
Documentation/security/self-protection.txt
View File

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

18
Documentation/sphinx/convert_template.sed Normal file
View File

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

141
Documentation/sphinx/kernel-doc.py Normal file
View File

@@ -0,0 +1,141 @@
# 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
import glob
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives
from sphinx.util.compat import Directive
from sphinx.ext.autodoc import AutodocReporter
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.unchanged,
'internal': directives.unchanged,
}
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]
export_file_patterns = []
# 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)
# FIXME: make this nicer and more robust against errors
if 'export' in self.options:
cmd += ['-export']
export_file_patterns = str(self.options.get('export')).split()
elif 'internal' in self.options:
cmd += ['-internal']
export_file_patterns = str(self.options.get('internal')).split()
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]
for pattern in export_file_patterns:
for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
env.note_dependency(os.path.abspath(f))
cmd += ['-export-file', 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, filename, lineoffset)
lineoffset += 1
node = nodes.section()
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
self.state.memo.title_styles, self.state.memo.section_level = [], 0
try:
self.state.nested_parse(result, 0, node, match_titles=1)
finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
return node.children
except Exception as e: # pylint: disable=W0703
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)

23
Documentation/sphinx/post_convert.sed Normal file
View File

@@ -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:]]*$//

365
Documentation/sphinx/rstFlatTable.py Normal file
View File

@@ -0,0 +1,365 @@
#!/usr/bin/env python3
# -*- coding: utf-8; mode: python -*-
# pylint: disable=C0330, R0903, R0912
u"""
flat-table
~~~~~~~~~~
Implementation of the ``flat-table`` reST-directive.
:copyright: Copyright (C) 2016 Markus Heiser
:license: GPL Version 2, June 1991 see linux/COPYING for details.
The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
the ``list-table`` with some additional features:
* *column-span*: with the role ``cspan`` a cell can be extended through
additional columns
* *row-span*: with the role ``rspan`` a cell can be extended through
additional rows
* *auto span* rightmost cell of a table row over the missing cells on the
right side of that table-row. With Option ``:fill-cells:`` this behavior
can changed from *auto span* to *auto fill*, which automaticly inserts
(empty) cells instead of spanning the last cell.
Options:
* header-rows: [int] count of header rows
* stub-columns: [int] count of stub columns
* widths: [[int] [int] ... ] widths of columns
* fill-cells: instead of autospann missing cells, insert missing cells
roles:
* cspan: [int] additionale columns (*morecols*)
* rspan: [int] additionale rows (*morerows*)
"""
# ==============================================================================
# imports
# ==============================================================================
import sys
from docutils import nodes
from docutils.parsers.rst import directives, roles
from docutils.parsers.rst.directives.tables import Table
from docutils.utils import SystemMessagePropagation
# ==============================================================================
# common globals
# ==============================================================================
# The version numbering follows numbering of the specification
# (Documentation/books/kernel-doc-HOWTO).
__version__ = '1.0'
PY3 = sys.version_info[0] == 3
PY2 = sys.version_info[0] == 2
if PY3:
# pylint: disable=C0103, W0622
unicode = str
basestring = str
# ==============================================================================
def setup(app):
# ==============================================================================
app.add_directive("flat-table", FlatTable)
roles.register_local_role('cspan', c_span)
roles.register_local_role('rspan', r_span)
# ==============================================================================
def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ==============================================================================
# pylint: disable=W0613
options = options if options is not None else {}
content = content if content is not None else []
nodelist = [colSpan(span=int(text))]
msglist = []
return nodelist, msglist
# ==============================================================================
def r_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ==============================================================================
# pylint: disable=W0613
options = options if options is not None else {}
content = content if content is not None else []
nodelist = [rowSpan(span=int(text))]
msglist = []
return nodelist, msglist
# ==============================================================================
class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
# ==============================================================================
# ==============================================================================
class FlatTable(Table):
# ==============================================================================
u"""FlatTable (``flat-table``) directive"""
option_spec = {
'name': directives.unchanged
, 'class': directives.class_option
, 'header-rows': directives.nonnegative_int
, 'stub-columns': directives.nonnegative_int
, 'widths': directives.positive_int_list
, 'fill-cells' : directives.flag }
def run(self):
if not self.content:
error = self.state_machine.reporter.error(
'The "%s" directive is empty; content required.' % self.name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return [error]
title, messages = self.make_title()
node = nodes.Element() # anonymous container for parsing
self.state.nested_parse(self.content, self.content_offset, node)
tableBuilder = ListTableBuilder(self)
tableBuilder.parseFlatTableNode(node)
tableNode = tableBuilder.buildTableNode()
# SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml()
if title:
tableNode.insert(0, title)
return [tableNode] + messages
# ==============================================================================
class ListTableBuilder(object):
# ==============================================================================
u"""Builds a table from a double-stage list"""
def __init__(self, directive):
self.directive = directive
self.rows = []
self.max_cols = 0
def buildTableNode(self):
colwidths = self.directive.get_column_widths(self.max_cols)
stub_columns = self.directive.options.get('stub-columns', 0)
header_rows = self.directive.options.get('header-rows', 0)
table = nodes.table()
tgroup = nodes.tgroup(cols=len(colwidths))
table += tgroup
for colwidth in colwidths:
colspec = nodes.colspec(colwidth=colwidth)
# FIXME: It seems, that the stub method only works well in the
# absence of rowspan (observed by the html buidler, the docutils-xml
# build seems OK). This is not extraordinary, because there exists
# no table directive (except *this* flat-table) which allows to
# define coexistent of rowspan and stubs (there was no use-case
# before flat-table). This should be reviewed (later).
if stub_columns:
colspec.attributes['stub'] = 1
stub_columns -= 1
tgroup += colspec
stub_columns = self.directive.options.get('stub-columns', 0)
if header_rows:
thead = nodes.thead()
tgroup += thead
for row in self.rows[:header_rows]:
thead += self.buildTableRowNode(row)
tbody = nodes.tbody()
tgroup += tbody
for row in self.rows[header_rows:]:
tbody += self.buildTableRowNode(row)
return table
def buildTableRowNode(self, row_data, classes=None):
classes = [] if classes is None else classes
row = nodes.row()
for cell in row_data:
if cell is None:
continue
cspan, rspan, cellElements = cell
attributes = {"classes" : classes}
if rspan:
attributes['morerows'] = rspan
if cspan:
attributes['morecols'] = cspan
entry = nodes.entry(**attributes)
entry.extend(cellElements)
row += entry
return row
def raiseError(self, msg):
error = self.directive.state_machine.reporter.error(
msg
, nodes.literal_block(self.directive.block_text
, self.directive.block_text)
, line = self.directive.lineno )
raise SystemMessagePropagation(error)
def parseFlatTableNode(self, node):
u"""parses the node from a :py:class:`FlatTable` directive's body"""
if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
self.raiseError(
'Error parsing content block for the "%s" directive: '
'exactly one bullet list expected.' % self.directive.name )
for rowNum, rowItem in enumerate(node[0]):
row = self.parseRowItem(rowItem, rowNum)
self.rows.append(row)
self.roundOffTableDefinition()
def roundOffTableDefinition(self):
u"""Round off the table definition.
This method rounds off the table definition in :py:member:`rows`.
* This method inserts the needed ``None`` values for the missing cells
arising from spanning cells over rows and/or columns.
* recount the :py:member:`max_cols`
* Autospan or fill (option ``fill-cells``) missing cells on the right
side of the table-row
"""
y = 0
while y < len(self.rows):
x = 0
while x < len(self.rows[y]):
cell = self.rows[y][x]
if cell is None:
x += 1
continue
cspan, rspan = cell[:2]
# handle colspan in current row
for c in range(cspan):
try:
self.rows[y].insert(x+c+1, None)
except: # pylint: disable=W0702
# the user sets ambiguous rowspans
pass # SDK.CONSOLE()
# handle colspan in spanned rows
for r in range(rspan):
for c in range(cspan + 1):
try:
self.rows[y+r+1].insert(x+c, None)
except: # pylint: disable=W0702
# the user sets ambiguous rowspans
pass # SDK.CONSOLE()
x += 1
y += 1
# Insert the missing cells on the right side. For this, first
# re-calculate the max columns.
for row in self.rows:
if self.max_cols < len(row):
self.max_cols = len(row)
# fill with empty cells or cellspan?
fill_cells = False
if 'fill-cells' in self.directive.options:
fill_cells = True
for row in self.rows:
x = self.max_cols - len(row)
if x and not fill_cells:
if row[-1] is None:
row.append( ( x - 1, 0, []) )
else:
cspan, rspan, content = row[-1]
row[-1] = (cspan + x, rspan, content)
elif x and fill_cells:
for i in range(x):
row.append( (0, 0, nodes.comment()) )
def pprint(self):
# for debugging
retVal = "[ "
for row in self.rows:
retVal += "[ "
for col in row:
if col is None:
retVal += ('%r' % col)
retVal += "\n , "
else:
content = col[2][0].astext()
if len (content) > 30:
content = content[:30] + "..."
retVal += ('(cspan=%s, rspan=%s, %r)'
% (col[0], col[1], content))
retVal += "]\n , "
retVal = retVal[:-2]
retVal += "]\n , "
retVal = retVal[:-2]
return retVal + "]"
def parseRowItem(self, rowItem, rowNum):
row = []
childNo = 0
error = False
cell = None
target = None
for child in rowItem:
if (isinstance(child , nodes.comment)
or isinstance(child, nodes.system_message)):
pass
elif isinstance(child , nodes.target):
target = child
elif isinstance(child, nodes.bullet_list):
childNo += 1
cell = child
else:
error = True
break
if childNo != 1 or error:
self.raiseError(
'Error parsing content block for the "%s" directive: '
'two-level bullet list expected, but row %s does not '
'contain a second-level bullet list.'
% (self.directive.name, rowNum + 1))
for cellItem in cell:
cspan, rspan, cellElements = self.parseCellItem(cellItem)
if target is not None:
cellElements.insert(0, target)
row.append( (cspan, rspan, cellElements) )
return row
def parseCellItem(self, cellItem):
# search and remove cspan, rspan colspec from the first element in
# this listItem (field).
cspan = rspan = 0
if not len(cellItem):
return cspan, rspan, []
for elem in cellItem[0]:
if isinstance(elem, colSpan):
cspan = elem.get("span")
elem.parent.remove(elem)
continue
if isinstance(elem, rowSpan):
rspan = elem.get("span")
elem.parent.remove(elem)
continue
return cspan, rspan, cellItem[:]

19
Documentation/sphinx/tmplcvt Executable file
View File

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

6
Documentation/sync_file.txt
View File

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

1
Documentation/sysctl/vm.txt
View File

@@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm:
- swappiness
- user_reserve_kbytes
- vfs_cache_pressure
- watermark_scale_factor
- zone_reclaim_mode
==============================================================

2
Documentation/thermal/intel_powerclamp.txt
View File

@@ -121,7 +121,7 @@ time is considered largely as a non-causal system where its behavior
cannot be based on the past or current input. Therefore, the
intel_powerclamp driver attempts to enforce the desired idle time
instantly as given input (target idle ratio). After injection,
powerclamp moniors the actual idle for a given time window and adjust
powerclamp monitors the actual idle for a given time window and adjust
the next injection accordingly to avoid over/under correction.
When used in a causal control system, such as a temperature control,

2
Documentation/usb/gadget_multi.txt
View File

@@ -36,7 +36,7 @@ configuration with CDC ECM which should work better under Linux.
** Windows host drivers
For the gadget two work under Windows two conditions have to be met:
For the gadget to work under Windows two conditions have to be met:
*** Detecting as composite gadget

2
Documentation/workqueue.txt
View File

@@ -169,7 +169,7 @@ resources, scheduled and executed.
WQ_UNBOUND
Work items queued to an unbound wq are served by the special
woker-pools which host workers which are not bound to any
worker-pools which host workers which are not bound to any
specific CPU. This makes the wq behave as a simple execution
context provider without concurrency management. The unbound
worker-pools try to start execution of work items as soon as

311
Documentation/zh_CN/CodingStyle
View File

@@ -25,20 +25,19 @@ Documentation/CodingStyle的中文翻译
Linux内核代码风格
这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我
不愿意把我的观点强加给任何人，不过这里所讲述的是我必须要维护的代码所遵守的风格，
并且我也希望绝大多数其他代码也能遵守这个风格。请在写代码时至少考虑一下本文所述的
风格。
不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也
希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。
首先，我建议你打印一份GNU代码规范，然后不要读它。烧了它，这是一个具有重大象征性
意义的动作。
首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义
的动作。
不管怎样，现在我们开始：
第一章：缩进
制表符是8个字符，所以缩进也是8个字符。有些异端运动试图将缩进变为4（乃至2）个字符
深，这几乎相当于尝试将圆周率的值定义为3。
制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！）
个字符深，这几乎相当于尝试将圆周率的值定义为 3。
理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕
连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。
@@ -50,8 +49,8 @@ Documentation/CodingStyle的中文翻译
简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的
时候可以给你警告。留心这个警告。
在switch语句中消除多级缩进的首选的方式是让“switch”和从属于它的“case”标签对齐于同
一列，而不要“两次缩进”“case”标签。比如：
在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签
对齐于同一列，而不要 “两次缩进” “case” 标签。比如：
switch (suffix) {
case 'G':
@@ -70,7 +69,6 @@ Documentation/CodingStyle的中文翻译
break;
}
不要把多个语句放在一行里，除非你有什么东西要隐藏：
if (condition) do_this;
@@ -90,25 +88,16 @@ Documentation/CodingStyle的中文翻译
每一行的长度的限制是 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,9 +123,9 @@ C语言风格中另外一个常见问题是大括号的放置。和缩进大小
body of function
}
全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道（
a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函数都是特殊的（在C语言中
，函数是不能嵌套的）。
全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道
(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C
函数是不能嵌套的）。
注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的
“while” 或者 if 语句中的 “else”，像这样：
@@ -166,8 +155,14 @@ a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函
if (condition)
action();
这点不适用于本身为某个条件语句的一个分支的单独语句。这时需要在两个分支里都使用大
括号。
和
if (condition)
do_this();
else
do_that();
这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号：
if (condition) {
do_this();
@@ -179,13 +174,16 @@ if (condition) {
3.1：空格
Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后
要加一个空格。值得注意的例外是sizeof、typeof、alignof和__attribute__，这些关键字
某些程度上看起来更像函数（它们在Linux里也常常伴随小括号而使用，尽管在C语言里这样
的小括号不是必需的，就像“struct fileinfo info”声明过后的“sizeof info”）。
要加一个空格。值得注意的例外是 sizeof、typeof、alignof 和 __attribute__，这些
关键字某些程度上看起来更像函数（它们在 Linux 里也常常伴随小括号而使用，尽管在 C 里
这样的小括号不是必需的，就像 “struct fileinfo info” 声明过后的 “sizeof info”）。
所以在这些关键字之后放一个空格：
if, switch, case, for, do, while
但是不要在 sizeof、typeof、alignof 或者 __attribute__ 这些关键字之后放空格。例如，
s = sizeof(struct file);
不要在小括号里的表达式两侧加空格。这是一个反例：
@@ -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” 是一个难以饶恕的错误。
全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函
数。如果你有一个可以计算活动用户数量的函数，你应该叫它“count_active_users()”或者
类似的名字，你不应该叫它“cntuser()”。
数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()”
或者类似的名字，你不应该叫它 “cntuser()”。
在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而
且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。
本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器
，它应该被称为“i”。叫它“loop_counter”并无益处，如果它没有被误解的可能的话。类似
的，“tmp”可以用来称呼任意类型的临时变量。
，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。
类似的，“tmp” 可以用来称呼任意类型的临时变量。
如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症
。请看第六章（函数）。
@@ -313,8 +314,8 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal
道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。
一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上
很简单的只有一个很长（但是简单）的case语句的函数，而且你需要在每个case里做很多很
小的事情，这样的函数尽管很长，但也是可以的。
很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做
很多很小的事情，这样的函数尽管很长，但也是可以的。
不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至
搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之
@@ -323,8 +324,8 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal
函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有
问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟
踪7个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你2
个星期前做过的事情。
踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你
2 个星期前做过的事情。
在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴
在它的结束大括号之下。比如：
@@ -344,8 +345,8 @@ EXPORT_SYMBOL(system_is_up);
虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是
无条件跳转指令。
当一个函数从多个位置退出并且需要做一些通用的清理工作的时候，goto的好处就显现出来
了。
当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。
如果并不需要清理操作，那么直接 return 即可。
理由是：
@@ -357,9 +358,10 @@ EXPORT_SYMBOL(system_is_up);
int fun(int a)
{
int result = 0;
char *buffer = kmalloc(SIZE);
char *buffer;
if (buffer == NULL)
buffer = kmalloc(SIZE, GFP_KERNEL);
if (!buffer)
return -ENOMEM;
if (condition1) {
@@ -367,14 +369,24 @@ int fun(int a)
...
}
result = 1;
goto out;
goto out_buffer;
}
...
out:
out_buffer:
kfree(buffer);
return result;
}
一个需要注意的常见错误是“一个 err 错误”，就像这样：
err:
kfree(foo->bar);
kfree(foo);
return ret;
这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个
错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。
第八章：注释
注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好
@@ -387,7 +399,7 @@ out:
些事情的原因。
当注释内核API函数时，请使用 kernel-doc 格式。请看
Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。
Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
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.
*/
注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只
声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段
小注释来解释它们的用途了。
@@ -417,30 +438,44 @@ Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...
所以你要么放弃 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)
(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 c-basic-offset 8))
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串
-*- linux-c -*-放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改
/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加
这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。
(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
auto-mode-alist))
到你的.emacs文件里。
不过就算你尝试让emacs正确的格式化代码失败了，也并不意味着你失去了一切：还可以用“
indent”。
不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用
“indent”。
不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不
过，这还不算太糟糕，因为就算是GNU indent的作者也认同K&R的权威性（GNU的人并不是坏
人，他们只是在这个问题上被严重的误导了），所以你只要给indent指定选项“-kr -i8”
过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是
坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8”
（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式
缩进源代码。
@@ -545,36 +580,52 @@ config ADFS_FS_RW
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
cpp手册对宏的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register
5) 在宏里定义类似函数的本地变量时命名冲突：
#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) 没有任何价值，应该避免这样做。
<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的
设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(),
dev_info()等等。对于那些不和某个特定设备相关连的信息，<linux/kernel.h>定义了
pr_debug()和pr_info()。
设备和驱动，并且被标记了正确的消息级别。这些宏有：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 文档以获取有关它们的详细信息。
传递结构体大小的首选形式是这样的：
@@ -586,6 +637,16 @@ vmalloc()。请参考API文档以获取有关它们的详细信息。
强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型
的转换是没有问题的。
分配一个数组的首选形式是这样的：
p = kmalloc_array(n, sizeof(...), ...);
分配一个零长数组的首选形式是这样的：
p = kcalloc(n, sizeof(...), ...);
两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。
第十五章：内联弊病
@@ -593,8 +654,8 @@ vmalloc()。请参考API文档以获取有关它们的详细信息。
函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是
这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核
会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导
致pagecache的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，将
耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。
致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，
将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例
外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能
@@ -672,23 +733,81 @@ Vim能够解释这样的标记：
式，或者使用其他可以产生正确的缩进的巧妙方法。
第十九章：内联汇编
在特定架构的代码中，你也许需要内联汇编来使用 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：
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
--
最后更新于2007年7月13日。

7
Makefile
View File

@@ -1366,6 +1366,8 @@ help:
@$(MAKE) $(build)=$(package-dir) help
@echo ''
@echo 'Documentation targets:'
@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
@echo ''
@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
@echo ''
@echo 'Architecture specific targets ($(SRCARCH)):'
@@ -1414,8 +1416,11 @@ $(help-board-dirs): help-%:
# Documentation targets
# ---------------------------------------------------------------------------
%docs: scripts_basic FORCE
DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs cleanmediadocs
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

431
scripts/kernel-doc
View File

@@ -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 any input FILE or -export-file FILE.
-internal Only output documentation for symbols that have NOT been
exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
in any input FILE or -export-file 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,11 @@ 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.
-export-file FILE Specify an additional FILE in which to look for
EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
-export or -internal. May be specified multiple times.
Other parameters:
-v Verbose output, more warnings and other information.
@@ -206,6 +217,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 +289,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,12 +324,23 @@ 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 @export_file_list;
my @build_time;
if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
(my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
@@ -327,6 +359,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 +377,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
# 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 $split_doc_state;
};
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 +480,30 @@ 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 "-export-file") {
my $file = shift @ARGV;
push(@export_file_list, $file);
} 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 +521,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 +536,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/) {
# print STDERR "parameter def '$1' = '$contents'\n";
if ($name =~ m/$type_param/) {
$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;
# Only warn on user specified duplicate section names.
if ($name ne $section_default) {
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;
}
}
}
@@ -512,15 +577,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 +1803,10 @@ sub output_blockhead_rst(%) {
my ($parameter, $section);
foreach $section (@{$args{'sectionlist'}}) {
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 +1823,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:: ";
@@ -1783,6 +1848,10 @@ sub output_function_rst(%) {
}
$count++;
$type = $args{'parametertypes'}{$parameter};
# RST doesn't like address_space tags at function prototypes
$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
# pointer-to-function
print $1 . $parameter . ") (" . $2;
@@ -1790,9 +1859,14 @@ 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/\[.*//;
@@ -1803,16 +1877,19 @@ sub output_function_rst(%) {
} else {
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(@_);
}
@@ -1823,7 +1900,8 @@ sub output_section_rst(%) {
$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 +1912,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;
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,25 +1941,32 @@ 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 "**Definition**\n\n";
print "::\n\n";
print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
foreach $parameter (@{$args{'parameterlist'}}) {
@@ -1903,7 +1992,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 +2002,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 +2059,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 +2565,6 @@ sub dump_function($$) {
sub reset_state {
$function = "";
%constants = ();
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
@@ -2481,8 +2574,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 +2638,7 @@ sub syscall_munge() {
}
}
sub process_state3_function($$) {
sub process_proto_function($$) {
my $x = shift;
my $file = shift;
@@ -2575,7 +2668,7 @@ sub process_state3_function($$) {
}
}
sub process_state3_type($$) {
sub process_proto_type($$) {
my $x = shift;
my $file = shift;
@@ -2649,6 +2742,42 @@ sub local_unescape($) {
return $text;
}
sub map_filename($) {
my $file;
my ($orig_file) = @_;
if (defined($ENV{'SRCTREE'})) {
$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
} else {
$file = $orig_file;
}
if (defined($source_map{$file})) {
$file = $source_map{$file};
}
return $file;
}
sub process_export_file($) {
my ($orig_file) = @_;
my $file = map_filename($orig_file);
if (!open(IN,"<$file")) {
print STDERR "Error: Cannot open file $file\n";
++$errors;
return;
}
while (<IN>) {
if (/$export_symbol/) {
$function_table{$2} = 1;
}
}
close(IN);
}
sub process_file($) {
my $file;
my $identifier;
@@ -2657,16 +2786,9 @@ 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;
}
else {
$file = $orig_file;
}
if (defined($source_map{$file})) {
$file = $source_map{$file};
}
$file = map_filename($orig_file);
if (!open(IN,"<$file")) {
print STDERR "Error: Cannot open file $file\n";
@@ -2681,15 +2803,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 +2827,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 +2870,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 +2901,16 @@ sub process_file($) {
$in_doc_sect = 1;
$in_purpose = 0;
$contents = $newcontents;
if ($contents ne "") {
$new_start_line = $.;
while ((substr($contents, 0, 1) eq " ") ||
substr($contents, 0, 1) eq "\t") {
$contents = substr($contents, 1);
}
if ($contents ne "") {
$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 +2924,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 +2935,7 @@ sub process_file($) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
$new_start_line = $.;
} else {
$contents .= "\n";
}
@@ -2801,18 +2946,31 @@ 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") {
@@ -2820,68 +2978,54 @@ sub process_file($) {
}
$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;
print STDERR "Warning(${file}:$.): ";
# nuke leading blank lines
if ($contents =~ /^\s*$/) {
$contents = "";
}
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
$inline_doc_state = STATE_INLINE_ERROR;
print STDERR "${file}:$.: warning: ";
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 +3042,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") {
@@ -2957,6 +3101,17 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
close(SOURCE_MAP);
}
if ($output_selection == OUTPUT_EXPORTED ||
$output_selection == OUTPUT_INTERNAL) {
push(@export_file_list, @ARGV);
foreach (@export_file_list) {
chomp;
process_export_file($_);
}
}
foreach (@ARGV) {
chomp;
process_file($_);